docs: add DR-009-Infra on harmonizing dependable_element with sphinx/… by antonkri · Pull Request #3097 · eclipse-score/score

antonkri · 2026-07-19T09:47:19Z

Add a proposed decision record describing how the dependable_element concept is interlocked with the existing sphinx/sphinx-needs based S-CORE process: sphinx/sphinx-needs stays the single source of truth, requirements/AoU are exported via TRLC (with a TRLC metamodel check) into dependable_element, and architecture PlantUML files are shared between both worlds. Includes overview and merge diagrams.

Add a proposed decision record describing how the dependable_element concept is interlocked with the existing sphinx/sphinx-needs based S-CORE process: sphinx/sphinx-needs stays the single source of truth, requirements/AoU are exported via TRLC (with a TRLC metamodel check) into dependable_element, and architecture PlantUML files are shared between both worlds. Diagrams are stored as static SVG images under _assets/ so they render both on GitHub and in the Sphinx build.

github-actions · 2026-07-20T06:51:59Z

The created documentation from the pull request is available at: docu-html

AlexanderLanin

Thanks a lot for the write-up. I have tried that myself and invested 40+ hours into it. With no tangible outcome, as I was not able to collect benefits of TRLC/Lobster.

AlexanderLanin · 2026-07-20T06:54:42Z

+proposes to **harmonize** them so that `dependable_element` becomes the
+*aggregation and traceability layer on top of* the existing sphinx-needs
+toolchain, rather than a competing parallel mechanism.


I assume this DR is about introducing dependable_element and about how to integrate it into S-CORE docs-as-code. Not just about harmonizaton.

In my opinion, the sphinx/sphinx-needs toolchain and dependable_element can be used together, with each having a slightly different focus. sphinx(-needs) focuses on requirements, architecture definition, and traceability more from a documentation perspective. dependable_element, on the other hand, focuses more on providing developer support to ensure, in a qualified manner, that all artifacts — including the traceability report — are valid and still reflect reality. This essentially covers what is currently handled manually through inspections and verification reports.

Some commercial solutions use a similar approach: on one hand, sphinx/sphinx-needs for the visualization of process artifacts, where validity checks are still needed to ensure that the rendered artifacts conform to the process metamodel. On the other hand, lean and easy-to-qualify solutions that produce, in a qualified manner, a traceability report — including additional checks to ensure that the artifacts and the traceability report still correspond to the reality in the source code.

AlexanderLanin · 2026-07-20T06:56:20Z

+technical solutions exhibit **instability**, and the overall **degree of
+automation can still be increased significantly**:
+
+- support for detailed design is completely missing


Contradiction: all detail design requirements are fully supported in S-CORE docs-as-code. Note however that there is almost no formal detail design documentation required by S-CORE process.

Indeed, there are currently not many requirements for detailed design in the s-core process documentation (and this is not fault of docs-as-code tooling). However, I would consider this a pitfall rather than a good design decision. dependable_element already provides a definition of a unit (which is completely missing in s-core) as well as a number of checks — for example, verifying that unit APIs correspond to the architecture diagram — that we could simply reuse.

AlexanderLanin · 2026-07-20T06:57:23Z

+- consistency checks between component and detailed design diagrams versus the
+  real dependencies in the build system and the structure in the source code
+  are missing


Note that we typically don't expect many detailed design diagrams. See S-CORE process documentation.

I guess, this is already covered by my comment above. I would consider this as a pitfall rather than a good design decision.

AlexanderLanin · 2026-07-20T06:59:23Z

+- sphinx / sphinx-needs does not allow, at least the way it is set up right
+  now, to specify accurate dependencies between requirements ↔ architecture ↔
+  source code ↔ tests. It treats everything as one big folder, where every


"accurate dependencies" are provided by S-CORE docs-as-code. That's normal traceability, isn't it?!

docs-as-code relies on sphinx. sphinx is not aware of our build system. It has its own workspace and this comes with some disadvantages, as you have to copy or mirror the whole data into sphinx workspace:

sphinx doesn't always know what has changed, if you want to be sure you are using newest data, you have to do a clean build. This takes time. This may be ok for automated CI workflows, but not for normal developer experience

sphinx doesn't know how you build your software, with which compiler flags, linker flags and so on. So there is no 100% guarantee you sphinx build is taking the same config, that is e.g. used for the final target build.

It can be difficult in the future to address variants. E.g. your modules can have different variants (= feature flags), that you can activate or deactivate. Then you will need to be very careful what are you copying or what you are not copying. "Just copying" some data from bazel output folder doesn't work. Bazel knows what belongs together, you not.

I do not say it doesn't work with sphinx(-needs), you can get this working. But I am not sure, that this is the right tool for this task.

AlexanderLanin · 2026-07-20T06:59:39Z

+  real dependencies in the build system and the structure in the source code
+  are missing
+- any kind of dependencies between tests / test executions and the generated
+  test reports in sphinx-needs are missing


full traceability is provided by S-CORE docs-as-code. See HowTo: Reference Docs in Tests

I guess, I've addressed this already in my previous comments

AlexanderLanin · 2026-07-20T07:02:31Z

+- the framework that most of the current process automation is built on —
+  **sphinx and sphinx-needs** — **cannot be properly qualified** for use in a
+  safety-critical context. It is a large, dynamically extensible documentation


To my knowledge we had this discussion already, and clarified that it is and it can be used in safety-critical context. This paragraph needs a little more clarity with correct wording by safety experts.

I would agree an this statement because of https://safety.useblocks.com/index.html. But we can always discuss potential concern in the process community meetings.

To my understanding, as written here https://safety.useblocks.com/usage/qualification.html#qualification-method, a second lean implementation is used to verify the output of sphinx/sphinx-needs. I would say, the proposed solution in this DR goes exactly in the same direction with the only difference, that we do not use needs.json but lobster.json for traceability documentation.

I guess, the problem is not to qualify all the tooling around sphinx-needs and metamodel.yaml we've built in score. That should work well. The problem is that needs.json, that we check, is produced by sphinx - a huge large framework with a lot of additional packages and config options you can use. To qualify sphinx can be very challenging.

If you guys know someone, who has done qualification of sphinx without building additional tooling to parse sphinx-needs in rst files separately from sphinx, be my guest.

AlexanderLanin · 2026-07-20T07:06:23Z

+  code → tests). This makes the relationships first-class, machine-checkable
+  edges instead of implicit links inside a documentation folder, and enables
+  incremental, cached re-evaluation of only the affected artifacts.


Current relationships are also "first-class, machine-checkable edges". Please clarify the difference and why it is an improvement.

explained here: #3097 (comment)

You do copy/link things from bazel build folder to sphinx workspace "manually", at least for verification report. I would not call it "first-class, machine-checkable edges".

AlexanderLanin · 2026-07-20T07:07:13Z

+- **Deterministic, hermetic checks.** Consistency and traceability checks run
+  as ordinary build actions and are therefore reproducible and qualifiable,
+  rather than living inside dynamic documentation plugins.


Current checks also run "deterministic and hermetic". Please clarify the difference and why it is an improvement.

To my understanding, sphinx has its own logic for resolution of links and dependencies. So we have like one "build-system" running in context of another. I am not sure it is deterministic and hermetic.

AlexanderLanin · 2026-07-20T07:09:43Z

+- **LOBSTER traceability aggregation.** The typed requirement and test
+  artifacts are converted to LOBSTER and combined into a per-element
+  traceability report, with the tracing tiers (component → feature →
+  stakeholder / assumed-system) enforced by the tooling.


Same as S-CORE docs-as-code, so this doesn't sound like a difference. Please clarify how this differs.

In case of docs-as-code, we have one central needs.json, as a result, the checks can be done only on this one needs.json. It means if you changes smth. in detailed design diagram and wants to know, whether this is still compliant with the implementation, then you will need to generate the whole needs.json and for this you will to build all the targets, e.g. verification report and for this to execute test and so on and so on.

In case of lobster, every bazel macro produces valid lobster.json reports, that can be used for validation. It means, to check that your detailed design is still valid, you will need to build only the lobster.json for detailed design. Only later, in the dependable_element, all lobster files are merged together in one for the final traceability check. That's the difference.

AlexanderLanin · 2026-07-20T07:10:00Z

+- **Aggregated, self-contained deliverable.** `dependable_element` collects all
+  artifacts of a *Safety Element out of Context (SEooC)* — requirements,
+  architecture, assumptions of use, dependability analysis, components, tests,
+  checklists and glossary — into a single, versioned deliverable with its own
+  HTML documentation and traceability report.


Same as S-CORE docs-as-code, so this doesn't sound like a difference. Please clarify how this differs.

yes, here at the end we get a complete lobster.json file, that is comparable with need.json. For the difference, please see the comment before.

MaximilianSoerenPollak · 2026-07-20T07:33:47Z

In my opinion this makes no sense to even start defining.

Older meeting minutes here: eclipse-score/communication#545 (comment)
We have had a meeting a while back where we decided we should get together and determine what even is the issue with this, what information exactly is needed for TRLC to work and how we can best provide it.

This meeting has not yet happened even after numerus attempts.
So in my mind the issue has lost importance and does not need to be addressed as the parties involved do not come together for a meeting.

I can not work on something that I do not know the requirements of, simple as that.

PandaeDo

Thank you for your perspective. But I would not agree from my experiences to your concerns against the actual solution, especially regarding qualification.

PandaeDo · 2026-07-20T07:39:49Z

+  the actual C++ sources (via a libclang toolchain) and validate the declared
+  architecture diagrams against the real dependency and code structure,
+  closing a gap that pure sphinx-needs cannot cover.
+- **LOBSTER traceability aggregation.** The typed requirement and test


I'm not a lawyer. But I guess we need to check if there is no licence conflict.

yes, we should.

PandaeDo · 2026-07-20T07:42:10Z

+The **merging / interlocking of these two approaches** — sphinx-needs as the
+low-friction authoring surface and single source of truth, `dependable_element`
+as the build-anchored automation and traceability layer on top of it — is
+expected to **drastically accelerate the roll-out of the S-CORE process into


Would not confirm this statement from the experiences we gained.

can you please be more concrete?

MaximilianSoerenPollak · 2026-07-20T07:53:33Z

+component requirements, architecture, assumptions of use, safety analyses,
+checklists — as **Sphinx-Needs** directives (`.. feat_req::`, `.. comp_req::`,
+…) inside `.rst`/`.md` sources. The build emits a project-wide `needs.json`,
+which serves two purposes: it is used both to **check that the need elements


Needs.json is only an output that can be dependency as an input to other docuementation builds.
The check that it is conform is done inside the sphinx-build and the needs.json might be part of that if it comes from an external source, but the internal local one does not play a role.

I agree and I don't see this as controversial to what I've written.

MaximilianSoerenPollak · 2026-07-20T07:54:54Z

+  assumptions of use) from them, and convert those to TRLC on the fly. As a
+  side benefit, the generated files are then also checked against the TRLC
+  metamodel, adding a second, independent validation layer on top of the
+  sphinx-needs metamodel check.


So we then have to upkeep and keep in sync and verify two different metamodels?

yes, true, that would be the consequence

MaximilianSoerenPollak · 2026-07-20T07:59:18Z

+- **Explicit, fine-grained dependencies.** Artifacts are wired together through
+  Bazel dependencies (requirements → architecture → components/units → source
+  code → tests). This makes the relationships first-class, machine-checkable
+  edges instead of implicit links inside a documentation folder, and enables
+  incremental, cached re-evaluation of only the affected artifacts.


What exactly is the difference here, compared to current implementation?
Why does the current implementation not work / provide what is needed?

I guess, I've explained this in my previous comments:

docs: add DR-009-Infra on harmonizing dependable_element with sphinx/… #3097 (comment)

docs: add DR-009-Infra on harmonizing dependable_element with sphinx/… #3097 (comment)

docs: add DR-009-Infra on harmonizing dependable_element with sphinx/… #3097 (comment)

MaximilianSoerenPollak · 2026-07-20T08:00:48Z

+- **Architecture-vs-reality validation.** The component and unit rules parse
+  the actual C++ sources (via a libclang toolchain) and validate the declared
+  architecture diagrams against the real dependency and code structure,
+  closing a gap that pure sphinx-needs cannot cover.


What about python and rust code, there this is not doable and therefore an issue?
Why is this a gap in the current implementation, was this ever a requirement to counter check the actual implementation against the needs you have defined?
IMO that should be part of the review process.

Yes, we will need to extend it for Rust.

Review process is a manual step, it is better, if you have this automated.

a-zw · 2026-07-20T11:21:18Z

+  source code ↔ tests. It treats everything as one big folder, where every
+  change forces everything to be regenerated


Suggested change

source code ↔ tests. It treats everything as one big folder, where every

change forces everything to be regenerated

source code ↔ tests.

- It treats everything as one big folder, where every

change forces everything to be regenerated

This seems to be two arguments mashed into one bullet point.

yes, will need to fix it, if the decision will be taken to merge this PR

a-zw · 2026-07-20T11:24:09Z

+  behaviour depends on a broad set of third-party Python extensions and
+  configuration that can change the output in ways that are difficult to
+  constrain and reproduce, and the validation logic (both the metamodel and
+  the traceability checks) lives inside these dynamic extensions rather than in


We don't need to qualify sphinx or sphinx-needs. We need to qualify score_docs_as_code (which internally uses sphinx and sphinx-needs).

see #3097 (comment)

a-zw · 2026-07-20T11:27:17Z

+
+### Non-Goals
+
+## Options Considered


I see two options to consider:

integrate TLRC and LOBSTER

extend score_docs_as_code

I've kept this empty intentionally, I just wanted to have the discussion first.

We cant really have a DR without options?

a-zw · 2026-07-20T14:11:27Z

+![Merging sphinx/sphinx-needs and dependable_element](_assets/DR-009-infra-merge.svg)
+
+### Goals and Requirements
+


My understanding after the Infra meeting what this proposal aims for:

Suggested change

- easy tool qualification

- enable unit design and traceability around it

- provide traceability report

a-zw · 2026-07-20T14:12:37Z

+## Options Considered
+
+## Evaluation
+


As a note: build speed should be an evaluation criterium

Add a mermaid classDiagram to DR-009-infra breaking dependable_element down into the individual rules_score rules, showing per-rule checks, the artifacts each rule contributes to the aggregated lobster.json, and the macro argument on each edge.

…diagram

antonkri · 2026-07-23T14:07:50Z

In my opinion this makes no sense to even start defining.

Older meeting minutes here: eclipse-score/communication#545 (comment) We have had a meeting a while back where we decided we should get together and determine what even is the issue with this, what information exactly is needed for TRLC to work and how we can best provide it.

This meeting has not yet happened even after numerus attempts. So in my mind the issue has lost importance and does not need to be addressed as the parties involved do not come together for a meeting.

I can not work on something that I do not know the requirements of, simple as that.

Agree, that's really a pity, that the meeting has not happened. This DR is an attempt to refresh the discussion.

…cks ubTrace)

a-zw · 2026-07-27T13:32:01Z

+report (empty when the rule adds nothing). Each arrow is labelled with the
+macro argument that wires the child rule into its parent.
+
+```mermaid


Suggested change

```mermaid

```{mermaid}

This should fix the Sphinx build.

a-zw · 2026-07-27T13:32:22Z

+labelled with the kind of check (per element, or graph over the whole model) or
+the relationship to the metamodel.
+
+```mermaid


Suggested change

```mermaid

```{mermaid}

This should fix the Sphinx build.

antonkri requested review from AlexanderLanin, MaximilianSoerenPollak and dcalavrezo-qorix as code owners July 19, 2026 09:47

github-project-automation Bot added this to S-CORE Roadmap and TLC - Technical Lead Circle Jul 19, 2026

github-project-automation Bot moved this to Backlog in S-CORE Roadmap Jul 19, 2026

antonkri requested review from PandaeDo, aschemmel-tech, masc2023 and pahmann as code owners July 19, 2026 09:50

antonkri force-pushed the ankr_sphinx_dep_elem branch from 4c9377a to e612bbe Compare July 20, 2026 06:47

AlexanderLanin requested changes Jul 20, 2026

View reviewed changes

antonkri marked this pull request as draft July 20, 2026 07:20

PandaeDo reviewed Jul 20, 2026

View reviewed changes

MaximilianSoerenPollak reviewed Jul 20, 2026

View reviewed changes

a-zw reviewed Jul 20, 2026

View reviewed changes

This was referenced Jul 21, 2026

feat(scripts_bazel): needs.json -> LOBSTER lobster-req-trace converter eclipse-score/docs-as-code#653

Closed

feat(scripts_bazel): needs.json -> LOBSTER lobster-req-trace converter eclipse-score/docs-as-code#654

Draft

anmittag assigned antonkri Jul 22, 2026

docs(DR-009): replace process-artifacts SVG with sphinx-needs checks …

47b058a

…diagram

eclipse-score deleted a comment from anmittag Jul 23, 2026

eclipse-score deleted a comment from MaximilianSoerenPollak Jul 23, 2026

docs(DR-009): note commercial solutions follow the same split (useblo…

8bf0361

…cks ubTrace)

antonkri force-pushed the ankr_sphinx_dep_elem branch from 0808f93 to 8bf0361 Compare July 24, 2026 06:16

a-zw suggested changes Jul 27, 2026

View reviewed changes

		source code ↔ tests. It treats everything as one big folder, where every
		change forces everything to be regenerated

		![Merging sphinx/sphinx-needs and dependable_element](_assets/DR-009-infra-merge.svg)

		### Goals and Requirements

+- easy tool qualification
+- enable unit design and traceability around it
+- provide traceability report

Uh oh!

Conversation

antonkri commented Jul 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jul 20, 2026

Uh oh!

AlexanderLanin left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

antonkri Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

antonkri Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

PandaeDo Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

antonkri Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MaximilianSoerenPollak commented Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

PandaeDo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

antonkri commented Jul 19, 2026 •

edited

Loading

antonkri Jul 23, 2026 •

edited

Loading

antonkri Jul 23, 2026 •

edited

Loading

PandaeDo Jul 20, 2026 •

edited

Loading

antonkri Jul 23, 2026 •

edited

Loading

MaximilianSoerenPollak commented Jul 20, 2026 •

edited

Loading

a-zw Jul 20, 2026 •

edited

Loading