Conversation
module_verification_report previously rendered both the module's own
components AND every Feature reachable from those components, mixing
module-scoped and platform-scoped statistics into a single report.
- module_verification_report.need: drop the feature-loop section
(Requirements/Architecture/Inspection Statistics per Feature). The
report now covers Components only, as its name implies.
- platform_verification_report.need (new): the feature-scoped
counterpart, listing every Feature in the current build (via the
existing needs_of_type("feat") helper) with the same statistics that
were removed from the module report.
Contributor
|
Documentation preview for this pull request is available at: |
Adds an optional report_version attribute on document Needs. When set, module_verification_report and platform_verification_report only show requirements (and the Features/Components that own them) with valid_from <= report_version. comp_req has no valid_from of its own, so its scope is inherited from the feat_req it is derived_from. Features/Components with no in-scope requirement are dropped from the report entirely instead of rendering an empty section. Unset/empty report_version keeps reports unscoped, matching prior behavior.
- ruff-format src/extensions/score_sphinx_needs_templates/__init__.py (2 lines that now fit on one line each). - Regenerate the 13 checked-in _expected/needs_json + needs_local.json fixtures under src/tests/docs_bzl/scenarios to include the new report_version extra-option schema entry, matching what test_docs_bzl_scenario_expected_output already wrote locally when it detected the diff (CI fails this test on purpose after auto-updating, so the updated files can be reviewed and committed).
Contributor
Author
|
@MaximilianSoerenPollak , @AlexanderLanin please review and ideally approve ;-) |
antonkri
marked this pull request as ready for review
September 18, 2026 13:54
antonkri
requested review from
AlexanderLanin,
MaximilianSoerenPollak,
a-zw,
dcalavrezo-qorix and
nradakovic
as code owners
September 18, 2026 13:54
There was a problem hiding this comment.
🟡 Changes recommended
Version expiration, duplicate Feature anchors, scalability, and missing integration coverage need resolution.
Get a fresh assessment by requesting another Copilot review.
Pull request overview
Splits verification reporting by scope and adds milestone-based requirement filtering.
Changes:
- Adds a platform-wide Feature verification report.
- Restricts module reports to Components.
- Adds
report_versionmetadata, filtering helpers, and updated snapshots.
File summaries
| File | Description |
|---|---|
src/needs_templates/platform_verification_report.need |
Adds the platform report template. |
src/needs_templates/module_verification_report.need |
Removes Feature sections and adds version filtering. |
src/extensions/score_sphinx_needs_templates/__init__.py |
Adds requirement-scope helpers. |
src/extensions/score_metamodel/metamodel.yaml |
Adds report_version. |
src/tests/docs_bzl/scenarios/subdirectory_bundle/producer/_expected/needs_json/needs.json |
Updates expected schema. |
src/tests/docs_bzl/scenarios/subdirectory_bundle/consumer/_expected/needs_json/needs.json |
Updates expected schema. |
src/tests/docs_bzl/scenarios/reference_integration/score_platform/_expected/needs_json/needs.json |
Updates expected schema. |
src/tests/docs_bzl/scenarios/reference_integration/modern_module/docs/components/unlinked_component/_expected/needs_local.json |
Updates expected schema. |
src/tests/docs_bzl/scenarios/reference_integration/modern_module/_expected/needs_json/needs.json |
Updates expected schema. |
src/tests/docs_bzl/scenarios/reference_integration/legacy_module/docs/components/component/_expected/needs_local.json |
Updates expected schema. |
src/tests/docs_bzl/scenarios/reference_integration/legacy_module/_expected/needs_json/needs.json |
Updates expected schema. |
src/tests/docs_bzl/scenarios/reference_integration/_expected/needs_local.json |
Updates expected schema. |
src/tests/docs_bzl/scenarios/nested_bundles/_expected/needs_json/needs.json |
Updates expected schema. |
src/tests/docs_bzl/scenarios/data_files_runfiles/_expected/needs_json/needs.json |
Updates expected schema. |
src/tests/docs_bzl/scenarios/data_files_runfiles/_expected/isolated_source_bundle_needs/needs.json |
Updates expected schema. |
src/tests/docs_bzl/scenarios/data_files_runfiles/_expected/data_bundle_needs/needs.json |
Updates expected schema. |
src/tests/docs_bzl/scenarios/basic_docs/_expected/needs_json/needs.json |
Updates expected schema. |
Review details
- Files reviewed: 17/17 changed files
- Comments generated: 4
- Review effort level: Balanced
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+214
to
+219
| valid_from = need.get("valid_from") | ||
| if valid_from: | ||
| try: | ||
| return _parse_version(valid_from) <= _parse_version(report_version) | ||
| except ValueError: | ||
| return False |
Comment on lines
+25
to
+26
| {% for feature in needs_of_type("feat")|unique(attribute="id")|sort(attribute="title")|list %} | ||
| {% set feature_reqs = linked_needs(feature["id"], "satisfied_by_back")|selectattr("type", "eq", "feat_req")|list %} |
| {# The feature Need supplies the work-product document selector and the | ||
| navigation anchor, the same way components do in module_verification_report. #} | ||
| {% set feature_slug_norm = feature_title|replace("_", "")|replace(" ", "")|lower %} | ||
| {% set feature_anchor = feature_title|replace("_", "-")|replace(" ", "-")|lower %} |
Comment on lines
+25
to
+27
| {% for feature in needs_of_type("feat")|unique(attribute="id")|sort(attribute="title")|list %} | ||
| {% set feature_reqs = linked_needs(feature["id"], "satisfied_by_back")|selectattr("type", "eq", "feat_req")|list %} | ||
| {% if any_req_in_scope(feature_reqs, report_version) %} |
Member
|
Thanks a lot for putting this together — this is a substantial and useful change! We'll then somehow split the review between .py code by docs-as-code team, and .need code by process team. |
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.
Why
module_verification_reportcurrently mixes two different scopes in one report:This makes the module report noisy for anything that cares only about its own components, and there was no way to get an aggregated, platform-wide view of all Features in one place.
What changed
src/needs_templates/module_verification_report.need: removed the Feature-loop section (Requirements/Architecture/Inspection Statistics per Feature reached viabelongs_to). The report now starts atComponentsand only covers the module's own components, as its name implies.src/needs_templates/platform_verification_report.need(new): the feature-scoped counterpart. Instead of resolving Features through one module's component graph, it collects every Feature in the current build via the existingneeds_of_type("feat")render-context helper, and renders the same Requirements/Architecture/Inspection statistics per Feature that were removed from the module report (plus a Feature Overview table, analogous to the module report's Component Overview).Version scoping (
report_version)Both reports can now be scoped to a release milestone instead of always showing everything:
src/extensions/score_metamodel/metamodel.yaml: new optionalreport_versionattribute on thedocumentneed type, using the samevMAJOR.MINOR[.PATCH]format already enforced forvalid_from/valid_until.src/extensions/score_sphinx_needs_templates/__init__.py: two new render-context helpers.req_in_scope(need, report_version)decides whether a single requirement Need is in scope.feat_req/stkh_reqcarryvalid_fromdirectly;comp_reqhas novalid_fromof its own, so it inherits scope from thefeat_reqit isderived_from. A requirement with no resolvablevalid_fromis excluded whenever areport_versionis set.any_req_in_scope(reqs, report_version)decides whether a Feature/Component has any requirement in scope..needtemplates use these helpers to:id in [...]the in-scope requirement IDs, andreport_versionkeeps a report fully unscoped (all Features/Components/requirements shown), which is whatdoc__platform_verification_report_latestand similar "latest" reports rely on — this is opt-in and backward compatible.