Skip to content

docs: add stp and rtm documents#1210

Draft
Ron (rjaegers) wants to merge 2 commits intomainfrom
docs/add-stp-and-rtm-documents
Draft

docs: add stp and rtm documents#1210
Ron (rjaegers) wants to merge 2 commits intomainfrom
docs/add-stp-and-rtm-documents

Conversation

@rjaegers
Copy link
Member

🚀 Hey, I have created a Pull Request

Description of changes

✔️ Checklist

  • I have followed the contribution guidelines for this repository
  • I have added tests for new behavior, and have not broken any existing tests
  • I have added or updated relevant documentation
  • I have verified that all added components are accounted for in the SBOM

@rjaegers Ron (rjaegers) requested a review from a team as a code owner March 20, 2026 11:20
Copilot AI review requested due to automatic review settings March 20, 2026 11:20
@rjaegers Ron (rjaegers) marked this pull request as draft March 20, 2026 11:20
@github-actions
Copy link
Contributor

github-actions bot commented Mar 20, 2026

⚠️MegaLinter analysis: Success with warnings

Descriptor Linter Files Fixed Errors Warnings Elapsed time
✅ ACTION actionlint 23 0 0 0.29s
✅ DOCKERFILE hadolint 3 0 0 0.31s
✅ JSON npm-package-json-lint yes no no 0.53s
✅ JSON prettier 21 4 0 0 0.75s
✅ JSON v8r 21 0 0 10.97s
✅ MARKDOWN markdownlint 12 0 0 0 1.32s
✅ MARKDOWN markdown-table-formatter 12 0 0 0 0.41s
✅ REPOSITORY checkov yes no no 28.06s
✅ REPOSITORY gitleaks yes no no 1.11s
✅ REPOSITORY git_diff yes no no 0.01s
⚠️ REPOSITORY grype yes no 42 46.91s
✅ REPOSITORY secretlint yes no no 2.64s
✅ REPOSITORY syft yes no no 2.56s
✅ REPOSITORY trivy yes no no 15.63s
✅ REPOSITORY trivy-sbom yes no no 0.52s
✅ REPOSITORY trufflehog yes no no 7.47s
⚠️ SPELL lychee 83 3 0 21.38s
✅ YAML prettier 31 0 0 0 1.3s
✅ YAML v8r 31 0 0 13.93s
✅ YAML yamllint 31 0 0 1.43s

Detailed Issues

⚠️ REPOSITORY / grype - 42 warnings
warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/continuous-integration.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/image-cleanup.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/issue-cleanup.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/issue-creation-tool-versions.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/linting-formatting.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/ossf-scorecard.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/pr-conventional-title.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/pr-image-cleanup.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/pr-report.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/release-build.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/release-please.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/update-dependencies.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/vulnerability-scan.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/wc-acceptance-test.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/wc-build-push.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/wc-dependency-review.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/wc-document-generation.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/wc-integration-test-docker.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/wc-integration-test-podman.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/wc-publish-templates.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/wc-sanitize-image-name.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/continuous-integration.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/image-cleanup.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/issue-cleanup.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/issue-creation-tool-versions.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/linting-formatting.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/ossf-scorecard.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/pr-conventional-title.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/pr-image-cleanup.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/pr-report.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/release-build.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/release-please.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/update-dependencies.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/vulnerability-scan.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/wc-acceptance-test.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/wc-build-push.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/wc-dependency-review.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/wc-document-generation.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/wc-integration-test-docker.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/wc-integration-test-podman.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/wc-publish-templates.yml

warning: A medium vulnerability in github-action package: step-security/harden-runner, version v2.15.1 was found at: /.github/workflows/wc-sanitize-image-name.yml

warning: 42 warnings emitted
⚠️ SPELL / lychee - 3 errors
[IGNORED] docker://pandoc/extra:3.9.0.0-ubuntu@sha256:72afa9c8d3300e5f10c9c4330e101725687f2179bffd912fb859c6d2ae85de62 | Unsupported: Error creating request client: builder error for url (docker://pandoc/extra:3.9.0.0-ubuntu@sha256:72afa9c8d3300e5f10c9c4330e101725687f2179bffd912fb859c6d2ae85de62)
[ERROR] https://www.conventionalcommits.org/en/v1.0.0/ | Network error: error sending request for url (https://www.conventionalcommits.org/en/v1.0.0/)
[403] https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads | Network error: Forbidden
[ERROR] https://www.contributor-covenant.org/ | Network error: error sending request for url (https://www.contributor-covenant.org/) Maybe a certificate error?
[IGNORED] https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/philips-software/amp-devcontainer | Unsupported: Error creating request client: builder error for url (vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/philips-software/amp-devcontainer)
📝 Summary
---------------------
🔍 Total..........126
✅ Successful.....121
⏳ Timeouts.........0
🔀 Redirected.......0
👻 Excluded.........0
❓ Unknown..........0
🚫 Errors...........3

Errors in .github/CODE_OF_CONDUCT.md
[ERROR] https://www.contributor-covenant.org/ | Network error: error sending request for url (https://www.contributor-covenant.org/) Maybe a certificate error?

Errors in .github/TOOL_VERSION_ISSUE_TEMPLATE.md
[403] https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads | Network error: Forbidden

Errors in .github/CONTRIBUTING.md
[ERROR] https://www.conventionalcommits.org/en/v1.0.0/ | Network error: error sending request for url (https://www.conventionalcommits.org/en/v1.0.0/)

See detailed reports in MegaLinter artifacts

You could have the same capabilities but better runtime performances if you use a MegaLinter flavor:

Your project could benefit from a custom flavor, which would allow you to run only the linters you need, and thus improve runtime performances. (Skip this info by defining FLAVOR_SUGGESTIONS: false)

  • Documentation: Custom Flavors
  • Command: npx mega-linter-runner@9.4.0 --custom-flavor-setup --custom-flavor-linters ACTION_ACTIONLINT,DOCKERFILE_HADOLINT,JSON_V8R,JSON_PRETTIER,JSON_NPM_PACKAGE_JSON_LINT,MARKDOWN_MARKDOWNLINT,MARKDOWN_MARKDOWN_TABLE_FORMATTER,REPOSITORY_CHECKOV,REPOSITORY_GIT_DIFF,REPOSITORY_GITLEAKS,REPOSITORY_GRYPE,REPOSITORY_SECRETLINT,REPOSITORY_SYFT,REPOSITORY_TRIVY,REPOSITORY_TRIVY_SBOM,REPOSITORY_TRUFFLEHOG,SPELL_LYCHEE,YAML_PRETTIER,YAML_YAMLLINT,YAML_V8R

MegaLinter is graciously provided by OX Security
Show us your support by starring ⭐ the repository

@github-actions
Copy link
Contributor

github-actions bot commented Mar 20, 2026

📦 Container Size Analysis

Note

Comparing ghcr.io/philips-software/amp-devcontainer-base:edgeghcr.io/philips-software/amp-devcontainer-base:pr-1210

📈 Size Comparison Table

OS/Platform Previous Current Change Trend
linux/amd64 144.74 MB 144.74 MB +1.18 kB (+0%) 🔼
linux/arm64 137.1 MB 137.1 MB 1.93 kB (0%) 🔽

@sonarqubecloud
Copy link

Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds generated quality-system documentation (STP + RTM) alongside the existing SRS, and updates the document-generation workflow to build these documents from the SBDL model (now including BATS integration tests).

Changes:

  • Add Jinja2 templates for a Software Test Plan (STP) and Requirements Traceability Matrix (RTM).
  • Extend the SRS template with Scope/References/Document Control content.
  • Update the reusable document-generation workflow to compile an SBDL model from both Gherkin features and a BATS test file, then render SRS/STP/RTM PDFs.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file
File Description
test/cpp/integration-tests.bats Adds an inline SBDL test trace annotation for a BATS test.
docs/templates/software-test-plan.md.j2 New STP template rendering tests traced to requirements.
docs/templates/software-requirements-specification.md.j2 Adds scope + document control sections to the generated SRS.
docs/templates/requirements-traceability-matrix.md.j2 New RTM template mapping requirements to tests and computing coverage summary.
.github/workflows/wc-document-generation.yml Generates STP/RTM markdown + PDFs and compiles the SBDL model from features + BATS.

Comment on lines 35 to +41
- uses: docker://pandoc/extra:3.9.0.0-ubuntu@sha256:72afa9c8d3300e5f10c9c4330e101725687f2179bffd912fb859c6d2ae85de62
with:
args: --template eisvogel --syntax-highlighting idiomatic --number-sections --output software-requirements-specification.pdf software-requirements-specification.md
- uses: docker://pandoc/extra:3.9.0.0-ubuntu@sha256:72afa9c8d3300e5f10c9c4330e101725687f2179bffd912fb859c6d2ae85de62
with:
args: --template eisvogel --syntax-highlighting idiomatic --number-sections --output software-test-plan.pdf software-test-plan.md
- uses: docker://pandoc/extra:3.9.0.0-ubuntu@sha256:72afa9c8d3300e5f10c9c4330e101725687f2179bffd912fb859c6d2ae85de62
Copy link

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Pandoc conversion steps are added without a name, which makes workflow logs harder to read (three identical uses entries). Add a descriptive name to each Pandoc step (e.g., indicating which document is being converted) to improve debuggability.

Suggested change
- uses: docker://pandoc/extra:3.9.0.0-ubuntu@sha256:72afa9c8d3300e5f10c9c4330e101725687f2179bffd912fb859c6d2ae85de62
with:
args: --template eisvogel --syntax-highlighting idiomatic --number-sections --output software-requirements-specification.pdf software-requirements-specification.md
- uses: docker://pandoc/extra:3.9.0.0-ubuntu@sha256:72afa9c8d3300e5f10c9c4330e101725687f2179bffd912fb859c6d2ae85de62
with:
args: --template eisvogel --syntax-highlighting idiomatic --number-sections --output software-test-plan.pdf software-test-plan.md
- uses: docker://pandoc/extra:3.9.0.0-ubuntu@sha256:72afa9c8d3300e5f10c9c4330e101725687f2179bffd912fb859c6d2ae85de62
- name: 📄 Generate SRS PDF
uses: docker://pandoc/extra:3.9.0.0-ubuntu@sha256:72afa9c8d3300e5f10c9c4330e101725687f2179bffd912fb859c6d2ae85de62
with:
args: --template eisvogel --syntax-highlighting idiomatic --number-sections --output software-requirements-specification.pdf software-requirements-specification.md
- name: 🧪 Generate STP PDF
uses: docker://pandoc/extra:3.9.0.0-ubuntu@sha256:72afa9c8d3300e5f10c9c4330e101725687f2179bffd912fb859c6d2ae85de62
with:
args: --template eisvogel --syntax-highlighting idiomatic --number-sections --output software-test-plan.pdf software-test-plan.md
- name: 🧩 Generate RTM PDF
uses: docker://pandoc/extra:3.9.0.0-ubuntu@sha256:72afa9c8d3300e5f10c9c4330e101725687f2179bffd912fb859c6d2ae85de62

Copilot uses AI. Check for mistakes.
python -m pip install gherkin-official==38.0.0 sbdl==1.21.3
- name: Build & Validate SBDL model
run: sbdl -m compile test/cpp/features/*.feature > amp-devcontainer.sbdl
run: sbdl -m compile test/cpp/integration-tests.bats test/cpp/features/*.feature > amp-devcontainer.sbdl
Copy link

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This run: line is long and mixes inputs/outputs in a single shell line. Consider switching this to a multi-line run: | block (and explicitly listing inputs) to improve readability and make future edits (adding more model inputs) less error-prone.

Suggested change
run: sbdl -m compile test/cpp/integration-tests.bats test/cpp/features/*.feature > amp-devcontainer.sbdl
run: |
set -Eeuo pipefail
sbdl -m compile \
test/cpp/integration-tests.bats \
test/cpp/features/*.feature \
> amp-devcontainer.sbdl

Copilot uses AI. Check for mistakes.
}

@test "valid code input should result in working executable using host compiler" {
# @sbdl test-comp-0001 is test { description is [[[[@-LINE]]]]; requirement is req-comp-0001 }
Copy link

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The SBDL annotation defines a test element with description, but the STP/RTM templates access test_elem['custom:title']. If custom:title is not set for this test element, document generation will fail or produce empty test names. Define custom:title (and optionally description) for the test, using the same pattern as the .feature SBDL blocks, so the templates can render test names reliably.

Suggested change
# @sbdl test-comp-0001 is test { description is [[[[@-LINE]]]]; requirement is req-comp-0001 }
# @sbdl test-comp-0001 is test { custom:title is [[[[@-LINE]]]]; description is [[[[@-LINE]]]]; requirement is req-comp-0001 }

Copilot uses AI. Check for mistakes.
@github-actions
Copy link
Contributor

Test Results

4 files   -   9  4 suites   - 9   0s ⏱️ - 18m 47s
1 tests  -  32  1 ✅  -  32  0 💤 ±0  0 ❌ ±0 
4 runs   - 133  4 ✅  - 133  0 💤 ±0  0 ❌ ±0 

Results for commit b41f257. ± Comparison against base commit 618174e.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants