Skip to content

docs(traceability): align dashboards with coverage metrics #485

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
FScholPer wants to merge 3 commits into from
Closed

docs(traceability): align dashboards with coverage metrics #485

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3f9664c
docs(traceability): align dashboards with coverage metrics
FScholPer Apr 13, 2026
e022e12
fix lint
FScholPer Apr 13, 2026
1ef858f
Merge branch 'main' into score-2775-traceability-dashboard
FScholPer Apr 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 34 additions & 4 deletions docs/internals/requirements/implementation_state.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,13 +19,23 @@ Implementation State Statistics
Overview
--------

.. note::
**Implementation vs. Traceability:** A requirement can be "implemented" in code
without having documentation links. This dashboard shows implementation status.

- **Not implemented**: ``implemented == 'NO'`` (actual TODO)
- **Implemented but incomplete docs**: ``implemented == 'YES|PARTIAL'`` and missing source_code_link OR missing testlink
- **Fully documented**: Both ``source_code_link`` and ``testlink`` present

The CI/CD gate check enforces minimum coverage thresholds for source_code_link and testlink.

.. needpie:: Requirements Status
:labels: not implemented, implemented but not tested, implemented and tested
:labels: not implemented, implemented (at least partial), fully documented
:colors: red,yellow, green

type == 'tool_req' and implemented == 'NO'
type == 'tool_req' and testlink == '' and (implemented == 'YES' or implemented == 'PARTIAL')
type == 'tool_req' and testlink != '' and (implemented == 'YES' or implemented == 'PARTIAL')
type == 'tool_req' and (implemented == 'YES' or implemented == 'PARTIAL') and (source_code_link == '' or testlink == '')
type == 'tool_req' and (implemented == 'YES' or implemented == 'PARTIAL') and source_code_link != '' and testlink != ''

In Detail
---------
Expand All @@ -45,13 +55,33 @@ In Detail

.. grid-item-card::

.. needpie:: Requirements with Codelinks
.. needpie:: Requirements with Source Code Links
:labels: no codelink, with codelink
:colors: red, green

type == 'tool_req' and source_code_link == ''
type == 'tool_req' and source_code_link != ''

.. grid-item-card::

.. needpie:: Requirements with Test Links
:labels: no testlink, with testlink
:colors: red, green

type == 'tool_req' and testlink == ''
type == 'tool_req' and testlink != ''

.. grid-item-card::

.. needpie:: Full Traceability (Code + Test Links)
:labels: fully linked, code only, test only, unlinked
:colors: green, orange, yellow, red

type == 'tool_req' and source_code_link != '' and testlink != ''
type == 'tool_req' and source_code_link != '' and testlink == ''
type == 'tool_req' and source_code_link == '' and testlink != ''
type == 'tool_req' and source_code_link == '' and testlink == ''

.. grid-item-card::

.. needpie:: Test Results
Expand Down
16 changes: 16 additions & 0 deletions docs/internals/requirements/requirements.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -731,6 +731,22 @@ Architecture Attributes
🔗 Code Linkage
----------------

**Codelink Coverage Status**

.. needpie:: Tool Requirements with Source Code Links
:labels: with codelink, without codelink
:colors: green, red

type == 'tool_req' and source_code_link != ''
type == 'tool_req' and source_code_link == ''

.. note::
This dashboard is complemented by an automated CI check using
``traceability_coverage``.

@AlexanderLanin AlexanderLanin Apr 14, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I wonder whether its easier / more convenient to extend those diagrams in some clever way. More effort... but otherwise we will always have huge discrepancies between thresholds and dashboards. That sounds like a maintenance nightmare.

.. needpie:: Tool Requirements with Source Code Links
  :labels: with codelink, without codelink
  :colors: green, red
  :minimum: 80, 0

  type == 'tool_req' and source_code_link != ''
  type == 'tool_req' and source_code_link == ''

@AlexanderLanin AlexanderLanin Apr 14, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Idea discussed with @MaximilianSoerenPollak. We can probably indeed solve it "like that". This avoids having thresholds and metrics showing different values.

@FScholPer FScholPer Apr 14, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

okay so how to go on then?

@MaximilianSoerenPollak MaximilianSoerenPollak Apr 14, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

We had the idea to solve it in ref-integration & the consumers.

The integration in re-fint would give you the dashboard for each repo that you wanted.
And the implementation in the consumers (like docs-as-code etc.) would give those repos a statistic as well in their own documentation.

The integration itself would be some thing like a 'generic' needpie function that can be called form the needpie via 'filter-func' attribute.
And then it calculates the things.
This way we have a dashboard and the statistic itself inside the docs therefore do not have risk to show different values.

If you want, we can do this and implement it, or you can give it a go as well. Just let us know.

@FScholPer FScholPer Apr 14, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

yeah but there should be also a dashboard in each of the modules as a must have as they are SEooC. This goes in the same direction as the DR-008

@MaximilianSoerenPollak MaximilianSoerenPollak Apr 14, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Yes that's why there is a duplication of this.
The code will be in ref-integration and in each of the modules. So they both have these dashboards / statistics.

@FScholPer FScholPer Apr 14, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

hm okay but then is there a way of just link it so that we have it in one central place ?

@MaximilianSoerenPollak MaximilianSoerenPollak Apr 14, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Most likely not as the code that needpie needs to reference hast to be in the same repository.

Though I will see if this is possible to maybe link somehow with a known path etc. If that is possible, then yes this would be the preferred way.

@FScholPer FScholPer Apr 14, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I can try to implement that generic filter-func and ping you until its available

The checker enforces minimum coverage thresholds. See
:doc:`/how-to/test_to_doc_links` for detailed information on combining
visual dashboards with CI/CD gates.

.. tool_req:: Supports linking to source code
:tags: Detailed Design & Code
:id: tool_req__docs_dd_link_source_code_link
Expand Down
Loading