docs: strengthen documentation templates for qualification friendliness#1337
Open
Ron (rjaegers) wants to merge 5 commits into
Open
docs: strengthen documentation templates for qualification friendliness#1337Ron (rjaegers) wants to merge 5 commits into
Ron (rjaegers) wants to merge 5 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.
Contributor
📦 Container Size AnalysisNote Comparing 📈 Size Comparison Table
|
Contributor
✅
|
| Descriptor | Linter | Files | Fixed | Errors | Warnings | Elapsed time |
|---|---|---|---|---|---|---|
| ✅ ACTION | actionlint | 23 | 0 | 0 | 0.25s | |
| ✅ DOCKERFILE | hadolint | 3 | 0 | 0 | 0.28s | |
| ✅ JSON | npm-package-json-lint | yes | no | no | 0.54s | |
| ✅ JSON | prettier | 28 | 6 | 0 | 0 | 1.18s |
| ✅ JSON | v8r | 28 | 0 | 0 | 14.59s | |
| ✅ MARKDOWN | markdownlint | 12 | 0 | 0 | 0 | 1.3s |
| ✅ MARKDOWN | markdown-table-formatter | 12 | 0 | 0 | 0 | 0.34s |
| ✅ REPOSITORY | checkov | yes | no | no | 28.69s | |
| ✅ REPOSITORY | gitleaks | yes | no | no | 1.17s | |
| ✅ REPOSITORY | git_diff | yes | no | no | 0.01s | |
| ✅ REPOSITORY | grype | yes | no | no | 56.74s | |
| osv-scanner | yes | 1 | no | 0.72s | ||
| ✅ REPOSITORY | secretlint | yes | no | no | 2.34s | |
| ✅ REPOSITORY | syft | yes | no | no | 2.29s | |
| ✅ REPOSITORY | trivy | yes | no | no | 13.62s | |
| ✅ REPOSITORY | trivy-sbom | yes | no | no | 0.23s | |
| ✅ REPOSITORY | trufflehog | yes | no | no | 6.64s | |
| lychee | 94 | 1 | 0 | 11.4s | ||
| ✅ YAML | prettier | 32 | 0 | 0 | 0 | 1.35s |
| ✅ YAML | v8r | 32 | 0 | 0 | 14.74s | |
| ✅ YAML | yamllint | 32 | 0 | 0 | 1.39s |
Detailed Issues
⚠️ SPELL / lychee - 1 error
📝 Summary
---------------------
🔍 Total..........139
🔗 Unique.........116
✅ Successful.....133
⏳ Timeouts.........0
🔀 Redirected......17
👻 Excluded.........0
❓ Unknown..........0
🚫 Errors...........1
⛔ Unsupported......1
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: 88 dirs visited, 293 inodes visited, 7 Extract calls, 25.266995ms elapsed, 25.267195ms 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
Ron (rjaegers)
temporarily deployed
to
acceptance-testing
GitHub Actions
Inactive
Ron (rjaegers)
changed the title
Ron (rjaegers)
temporarily deployed
to
acceptance-testing
GitHub Actions
Inactive
|
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 updates the documentation generation workflow and refines the requirements documentation for the project. The main improvements include switching from a Software Test Plan (STP) to a Software Verification Plan (SVP), enhancing the requirements specification with clearer scope and terminology, and updating workflow steps to use more maintainable and comprehensive commands.
Documentation generation and template changes:
The Software Test Plan (
software-test-plan.md.j2) and related PDF generation steps have been replaced with a Software Verification Plan (software-verification-plan.md.j2), reflecting a shift in terminology and focus. All references in the workflow and output files are updated accordingly. [1] [2] [3]The SBDL model build step now uses a recursive compile (
sbdl -m compile -r .) instead of listing files explicitly, simplifying maintenance and ensuring all relevant files are included.Requirements specification enhancements:
The Software Requirements Specification template (
software-requirements-specification.md.j2) has been expanded with a more detailed Purpose, Scope, and Abstract, clarifying the project's goals, in-scope/out-of-scope items, and philosophy regarding qualification and objective evidence.The References and Terminology sections have been updated to add missing standards (e.g., SPDX, in-toto), clarify definitions (e.g., Attestation, Provenance, SBOM), and improve overall traceability. [1] [2]
Requirement rendering now includes explicit Requirement and Rationale subsections for each requirement, improving clarity and auditability.
Test traceability and workflow improvements:
Removed/renamed files:
software-test-plan.md.j2template has been deleted, as the new SVP replaces it.✔️ Checklist