docs: strengthen documentation template for qualification friendliness#1337
Open
Ron (rjaegers) wants to merge 3 commits into
Open
docs: strengthen documentation template for qualification friendliness#1337Ron (rjaegers) wants to merge 3 commits into
Ron (rjaegers) wants to merge 3 commits into
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Strengthens the Software Requirements Specification (SRS) Jinja2 template to be more qualification-friendly by expanding introductory content, tightening scope definitions, and improving requirements readability/traceability.
Changes:
- Expanded “Purpose” and added a richer “Abstract” describing project intent and qualification-friendly philosophy.
- Refined “Scope” in/out boundaries and updated the “References” and “Terminology and Abbreviations” tables with additional supply-chain/security-related entries.
- Added explicit
_Requirement_/_Rationale_labels to each rendered requirement to improve structure and traceability.
| | RFC 2119 | [Key words for use in RFCs to Indicate Requirement Levels](https://www.rfc-editor.org/rfc/rfc2119) | | ||
| | SemVer | [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) | | ||
| | SLSA | [Supply-chain Levels for Software Artifacts v1.0](https://slsa.dev/spec/v1.0/levels) | | ||
| | SPDX | [System Package Data Exchange Specification v2.3](https://spdx.github.io/spdx-spec/v2.3/) | |
Contributor
📦 Container Size AnalysisNote Comparing 📈 Size Comparison Table
|
Contributor
✅
|
| Descriptor | Linter | Files | Fixed | Errors | Warnings | Elapsed time |
|---|---|---|---|---|---|---|
| ✅ ACTION | actionlint | 23 | 0 | 0 | 0.18s | |
| ✅ DOCKERFILE | hadolint | 3 | 0 | 0 | 0.2s | |
| ✅ JSON | npm-package-json-lint | yes | no | no | 0.53s | |
| ✅ JSON | prettier | 28 | 6 | 0 | 0 | 0.94s |
| ✅ JSON | v8r | 28 | 0 | 0 | 14.13s | |
| ✅ MARKDOWN | markdownlint | 12 | 0 | 0 | 0 | 1.28s |
| ✅ MARKDOWN | markdown-table-formatter | 12 | 0 | 0 | 0 | 0.36s |
| ✅ REPOSITORY | checkov | yes | no | no | 27.66s | |
| ✅ REPOSITORY | gitleaks | yes | no | no | 1.12s | |
| ✅ REPOSITORY | git_diff | yes | no | no | 0.02s | |
| ✅ REPOSITORY | grype | yes | no | no | 55.97s | |
| osv-scanner | yes | 1 | no | 1.05s | ||
| ✅ REPOSITORY | secretlint | yes | no | no | 2.35s | |
| ✅ REPOSITORY | syft | yes | no | no | 2.57s | |
| ✅ REPOSITORY | trivy | yes | no | no | 14.62s | |
| ✅ REPOSITORY | trivy-sbom | yes | no | no | 0.32s | |
| ✅ REPOSITORY | trufflehog | yes | no | no | 6.37s | |
| lychee | 94 | 2 | 0 | 11.45s | ||
| ✅ YAML | prettier | 32 | 0 | 0 | 0 | 1.3s |
| ✅ YAML | v8r | 32 | 0 | 0 | 15.04s | |
| ✅ YAML | yamllint | 32 | 0 | 0 | 1.26s |
Detailed Issues
⚠️ SPELL / lychee - 2 errors
📝 Summary
---------------------
🔍 Total..........139
🔗 Unique.........116
✅ Successful.....132
⏳ Timeouts.........0
🔀 Redirected......17
👻 Excluded.........0
❓ Unknown..........0
🚫 Errors...........2
⛔ Unsupported......2
Errors in .github/CODE_OF_CONDUCT.md
[ERROR] https://www.contributor-covenant.org/ (at 76:42) | Network error: Connection reset by peer (os error 104)
Errors in .github/TOOL_VERSION_ISSUE_TEMPLATE.md
[403] https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads (at 38:7) | Rejected status code: 403 Forbidden
Hint: Followed 17 redirects. You might want to consider replacing redirecting URLs with the resolved URLs. Use verbose mode (`-v`/`-vv`) to see redirection details.
Hint: You can configure accepted/rejected response codes with `-a` or `--accept`
⚠️ REPOSITORY / osv-scanner - 1 error
Scanning dir .
Starting filesystem walk for root: /
Scanned .devcontainer/cpp/requirements.txt file and found 20 packages
Scanned package-lock.json file and found 73 packages
Scanned test/rust/workspace/cargo/Cargo.lock file and found 1 package
Scanned test/rust/workspace/test/Cargo.lock file and found 1 package
Scanned test/rust/workspace/cortex-m/Cargo.lock file and found 20 packages
Scanned test/rust/workspace/clippy/Cargo.lock file and found 1 package
Scanned test/rust/workspace/cortex-mf/Cargo.lock file and found 20 packages
End status: 90 dirs visited, 297 inodes visited, 7 Extract calls, 24.473347ms elapsed, 24.473547ms wall time
Total 2 packages affected by 2 known vulnerabilities (0 Critical, 0 High, 0 Medium, 0 Low, 2 Unknown) from 1 ecosystem.
0 vulnerabilities can be fixed.
+-----------------------------------+------+-----------+------------+---------+---------------+------------------------------------------+
| OSV URL | CVSS | ECOSYSTEM | PACKAGE | VERSION | FIXED VERSION | SOURCE |
+-----------------------------------+------+-----------+------------+---------+---------------+------------------------------------------+
| https://osv.dev/RUSTSEC-2026-0110 | | crates.io | bare-metal | 0.2.5 | -- | test/rust/workspace/cortex-m/Cargo.lock |
| https://osv.dev/RUSTSEC-2026-0110 | | crates.io | bare-metal | 0.2.5 | -- | test/rust/workspace/cortex-mf/Cargo.lock |
+-----------------------------------+------+-----------+------------+---------+---------------+------------------------------------------+
Notices
📣 MegaLinter 9.5.0 is out! Discover the new features and security recommendations in the release announcement. (Skip this info by defining SECURITY_SUGGESTIONS: false)
See detailed reports in MegaLinter artifacts
You could have the same capabilities but better runtime performances if you use a MegaLinter flavor:
- oxsecurity/megalinter/flavors/salesforce@v9.5.0 (59 linters)
- oxsecurity/megalinter/flavors/javascript@v9.5.0 (62 linters)
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.5.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_OSV_SCANNER,REPOSITORY_SECRETLINT,REPOSITORY_SYFT,REPOSITORY_TRIVY,REPOSITORY_TRIVY_SBOM,REPOSITORY_TRUFFLEHOG,SPELL_LYCHEE,YAML_PRETTIER,YAML_YAMLLINT,YAML_V8R
Show us your support by starring ⭐ the repository
Contributor
📦 Container Size AnalysisNote Comparing 📈 Size Comparison Table
|
Contributor
📦 Container Size AnalysisNote Comparing 📈 Size Comparison Table
|
Ron (rjaegers)
temporarily deployed
to
acceptance-testing
GitHub Actions
Inactive
Contributor
📦 Container Size AnalysisNote Comparing 📈 Size Comparison Table
|
Contributor
Ron (rjaegers)
temporarily deployed
to
acceptance-testing
GitHub Actions
Inactive
Ron (rjaegers)
changed the title
|
Comment on lines
+69
to
74
| | OCI | [Open Container Initiative Image Specification](https://github.com/opencontainers/image-spec/blob/main/spec.md) | | ||
| | RFC 2119 | [Key words for use in RFCs to Indicate Requirement Levels](https://www.rfc-editor.org/rfc/rfc2119) | | ||
| | SemVer | [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) | | ||
| | SLSA | [Supply-chain Levels for Software Artifacts v1.0](https://slsa.dev/spec/v1.0/levels) | | ||
| | SPDX | [Software Package Data Exchange Specification v2.3](https://spdx.github.io/spdx-spec/v2.3/) | | ||
|
|
Comment on lines
39
to
+41
| - **Gherkin verification tests**: Scenario-based tests defined in Gherkin feature files and executed with Playwright. These tests verify behavioral requirements at the system level. | ||
| - **BATS integration tests**: Shell-based integration tests defined in BATS (Bash Automated Testing System) files. These tests verify tool availability, version alignment, and end-to-end compilation and analysis workflows. | ||
| - **Hard-gates**: continuous workflow gates that raise an error when a condition is not met. |
Comment on lines
33
to
+34
| - name: Build & Validate SBDL model | ||
| run: sbdl -m compile test/cpp/integration-tests.bats test/cpp/features/*.feature test/embedded-cpp/integration-tests.bats test/embedded-cpp/features/*.feature > amp-devcontainer.sbdl | ||
| run: sbdl -m compile .github/workflows/wc-build-push-test.yml test/cpp/integration-tests.bats test/cpp/features/*.feature test/embedded-cpp/integration-tests.bats test/embedded-cpp/features/*.feature > amp-devcontainer.sbdl |
Comment on lines
33
to
+34
| - name: Build & Validate SBDL model | ||
| run: sbdl -m compile test/cpp/integration-tests.bats test/cpp/features/*.feature test/embedded-cpp/integration-tests.bats test/embedded-cpp/features/*.feature > amp-devcontainer.sbdl | ||
| run: sbdl -m compile .github/workflows/wc-build-push-test.yml test/cpp/integration-tests.bats test/cpp/features/*.feature test/embedded-cpp/integration-tests.bats test/embedded-cpp/features/*.feature > amp-devcontainer.sbdl |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
🚀 Hey, I have created a Pull Request
Description of changes
This pull request makes significant improvements to the
docs/templates/software-requirements-specification.md.j2template, enhancing the clarity, completeness, and professionalism of the software requirements specification for the amp-devcontainer project. The changes expand the document's introductory sections, clarify scope, update references, and improve terminology definitions.Key improvements include:
Expanded Introduction and Scope:
References and Terminology:
Requirements Formatting:
✔️ Checklist