eclipse-score / eclipse-score/baselibs
Remove redundant Sphinx-Needs scope tags and simplify report filters
- Dominant language
- C++
- Stars
- 26
- Forks
- 85
- Avg merge
- 2d 13h
- Merged PRs (30d)
- 47
Description
## Problem
The documentation contains 29 `needextend` directives across 20 RST files that append scope tags such as `baselibs`, `bitmanipulation`, `containers`, and `logging`.
These tags duplicate information that may already be available from the need type, document path, or requirement-to-component relation:
- all locally authored needs in this repository belong to Baselibs;
- component requirement and inspection documents identify their component through `docname`;
- component requirements link to their implementing component using `satisfied_by`.
This creates noisy metadata, hides the actual selection criteria, and has drifted: Result needs are tagged `result_lib` while the checklist expects `result_library`; log architecture needs are tagged `logging` while the checklist expects `log`.
## Scope
1. Inventory every `needextend` directive and every in-repository consumer of its tags.
2. Evaluate and select the most appropriate selector for each report or checklist:
- structural scope based on need type and document path;
- `satisfied_by` for component requirement allocation;
- a retained tag only where it has independent semantic value.
3. Investigate a suitable way to select AoUs by component when using relation-based filters:
- determine whether existing links such as `covers` or architecture `fulfils` provide the required semantics;
- if not, evaluate a metamodel extension or another explicit, validated relation;
- do not add `satisfied_by` to `aou_req` without a metamodel and semantic decision.
- Changes in https://github.com/eclipse-score/docs-as-code may be needed to achieve this.
4. Remove `needextend` directives that only append redundant Baselibs or component-scope tags after their consumers have been migrated.
5. Resolve the `result_lib`/`result_library` and `logging`/`log` inconsistencies, either by removing the obsolete filter/tag pair or by adopting one canonical name.
6. Preserve tags needed by external consumers or with a documented non-redundant purpose.
## Acceptance Criteria
- [ ] Every retained `needextend` tag has a documented consumer and purpose.
- [ ] Module safety-plan requirement and AoU status reporting remains complete after migration.
- [ ] Component inspection tables retain their intended component requirement and AoU scope.
- [ ] A documented decision exists for component-scoped AoU selection, including whether a metamodel change is needed.
- [ ] `satisfied_by` is evaluated as a possible selector for `comp_req` without assuming it applies to AoUs.
- [ ] Result and log inspection tables no longer have empty output caused by mismatched tag names.
- [ ] `bazel run //:docs` completes without new documentation or metamodel errors.
Contributor guide
No contributing guide indexed for this repository
Research direction
Inventory the 29 needextend directives across the 20 RST files and trace every in-repository consumer of their tags. Start with the report and checklist filters, then evaluate structural selectors, satisfied_by, and existing AoU relations before deciding whether a metamodel change is needed. Done means redundant tags are removed, retained tags have documented consumers, inspection output remains complete, and bazel run //:docs passes.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100