Decision Record 004 #1930
Decision Record 004 #1930
Conversation
a-zw
requested review from
AlexanderLanin,
PhilipPartsch,
aschemmel-tech,
dcalavrezo-qorix,
masc2023 and
pahmann
as code owners
|
|
|
The created documentation from the pull request is available at: docu-html |
dcalavrezo-qorix
left a comment
dcalavrezo-qorix
left a comment
There was a problem hiding this comment.
How do you handle different versions for Option S ?
|
also, not a big fan of emojis in documentation ( but that's just my taste) |
I essentially want something clearly saying "good" or "bad" and red vs green does that. In Confluence there is an easy way to make it "green plus" or "red minus": 
Unfortunately, there are no corresponding emojis afaik. Hence the smiley and heart thingies. |
Version as in "0.5" or "1.0"? That would simply be separate builds. Nothing changes from the status quo. Do you see a need to do something @dcalavrezo-qorix ? |
ubmarco
left a comment
ubmarco
left a comment
There was a problem hiding this comment.
I want to discuss this!
There are concepts out there for bidirectional links.
useblocks/sphinx-needs#1166
useblocks/sphinx-needs#1220
It's not required to put all documentation into a single project.
This comes down to a multi stage build in which stage 1 builds needs.json and ignores broken links to generate the project inventory.
Then needs.json files are exchanged for a full stage 2 build of the projects.
Stage 1 is commonly fast as HTML is not written.
This leads to a non-cyclic Bazel build graph.
It's some effort however to model this in Bazel.
Is bidirectional linking a hard requirement or just user convenience? Because not requiring this makes our lives much easier.
If you wish we can chat about this tomorrow.
FScholPer
left a comment
FScholPer
left a comment
There was a problem hiding this comment.
Can we please divide into traceability tests and doc generation. I still would see that before we dive deeper.
|
So these are independent topics:
This DR is about 1. For 3. there are other DR issues raised by @AlexanderLanin that we should follow up. The bi-directional linking actually depends on these DR, so starting there is a reasonable choice for me. |
The concepts you reference should be Option M in the decision record. I can add these references to the DR.
Yes, that is precisely the essential question. What you describe as "makes our lives much easier" is probably the "bureaucracy" criterium in the DR? The tradeoff is the UX for people who just want nice documentation. In other words, depending on whose lives we want to make easier, we must pick either option S or M. |
a-zw
force-pushed
the
dr-docs-traceability
branch
from
62baef6 to
54143b5
Compare
| 1. We want to enable each module to work independently and efficiently, i.e. build their own documentation quickly. | ||
| (Sphinx builds are annoyingly slow in any case but that is not the core point of this decision record.) | ||
| 2. We want a complete and consistent documention for a release, i.e. everything with backlinks. | ||
| Regulations only require that *eventually* though and during development slight inconsistencies are acceptable. |
There was a problem hiding this comment.
Inconsistencies will lead to build failures during development. I would address this more to convinience: we do not have a hosted html version of a every specific dependency/version.
There was a problem hiding this comment.
There can be inconsistencies without build failures.
For example, let's assume Platform has backlinks to component requirements in modules, such as Com. Now Com adds a new component requirement derived from an existing feature requirement in Platform. Platform documentation does not yet show the backlink for this simply because it has not been rebuilt yet. Thus the github.io documentation of Platform and Com are inconsistent.
There was a problem hiding this comment.
Platform will never have backlinks to com :)
Platform would be generic, and is not aware of who exactly implements those requirements.
That information is always only available at integration time.
That's why I have 4 platform websites in this drawing: https://github.com/AlexanderLanin/score/blob/docs-multirepo/docs/_tooling/decision-records/_assets/multirepo_bidirectional.drawio.svg
There was a problem hiding this comment.
Wait, now you confused me.
"Platform" is the eclipse-score/score repository for me. It does not reference the modules. However, linking happens the other way round because modules reference the higher-level requirements in Platform. This implies backlinks in Platform if we want bi-directional traceability.
If these backlinks are visible on the eclipse-score.github.io/score/ website or just on eclipse-score.github.io/reference_integration/ is intentionally left open by this decision record. The Platform repository can be configured either way.
| 2. We want a complete and consistent documention for a release, i.e. everything with backlinks. | ||
| Regulations only require that *eventually* though and during development slight inconsistencies are acceptable. | ||
| 3. Some modules want backlinks even if the slows down the doc build. | ||
| For example, Platform wants backlinks for the feature requirements. |
There was a problem hiding this comment.
platform=score, and feature requirements are in score. Backlinks to what?
There was a problem hiding this comment.
Component requirements should be in the modules but currently they are in platform (=score). They derive from feature requirements which should be in platform, so requirements in modules reference requirements in platform.
One probably wants to know which modules are involved for certain features, thus you want to see the backlinks in the feature requirements in the platform documentation.
There was a problem hiding this comment.
Wow that's hard to read 😆
I guess this is answered by the previous comment/image?
| Current implementation for external needs means modules reference external ids with a prefix. | ||
| This prefixed id does not exist in a mega-build which results in Sphinx warnings. | ||
|
|
||
| 😡 Bureaucracy: Modules must not use prefixes for external needs because it breaks the integration build. |
There was a problem hiding this comment.
Modules do use such prefixes. So the overhead is, that we need to remove them on the fly when building such a full build. Or we need to prefix the needs on the fly to avoid name collisions.
There was a problem hiding this comment.
We can just remove the prefixes. That should work without conflicts because id schemas already involve namespaces via process. It just means a little bit of refactoring work... s/PROCESS_//g
| Options Considered | ||
| ------------------ | ||
|
|
||
| Option S: Single documentation build |
There was a problem hiding this comment.
Option S will work better when multiple repositories are local with local_module_override?!
There was a problem hiding this comment.
I don't understand. What do you mean by "local_module_override"? Also, "better" in what way?
There was a problem hiding this comment.
I thought we have an issue for that, but I cannot find it. So I'll try to explain the use case here:
When I have two repos cloned. Both with docs-as-code, and one depends on the other.
e.g. docs-as-code repo and process repo.
When I need to edit them in sync, I would create a local_module_override in docs-as-code (or use some fancy bazel command line flag). However, now when I build the html pages, or use the live_preview feature. The generated pages do not link to my local process html pages.
As far as I understand that would be implicitly solved by option S, since I get a single big website. While option M is quite difficult, as it needs to know the other url. Which is probably on localhost, but with a random port number.
There was a problem hiding this comment.
First, may you never have the need to "edit them in sync" because you already got into a mess then. 🤞
Yes, technically an advantage for S but I don't think it is a relevant one because this sync-editing will be painful in either case.
aschemmel-tech
left a comment
aschemmel-tech
left a comment
There was a problem hiding this comment.
see inline comment
| Bureaucracy, 😡, 💚 | ||
| Speed, 😡, 💚 | ||
|
|
||
| Since UX is more important than speed and bureaucracy, option S is best. |
There was a problem hiding this comment.
Discussion result from the processes community - see https://github.com/orgs/eclipse-score/discussions/407#discussioncomment-14760276 : we would be in favour of option M, as the "UX" advantage between S and M we consider as small.
| By using them on both sides, bi-directional traceability can be achieved without circular dependencies. | ||
|
|
||
| The documentation of a single module may be outdated with respect to external needs, i.e. backlinks. | ||
| Just imagine a new module is created which uses Baselibs but Baselibs makes no changes, so the documentation is never rebuilt. |
There was a problem hiding this comment.
How can this fail? If there is a dependency to baselibs, then this is modeled in Bazel and the needs.json / objects.inv artifacts are provided by the build system to the new module.
There was a problem hiding this comment.
It doesn't fail. The new module is fine.
The inconsistency is that the baselibs documentation hosted on github.io does not show any backlinks. It is "outdated". This is until someone triggers a rebuild. (All of this assumes baselibs is configured to consider all modules for backlinks)
There was a problem hiding this comment.
Ok got it, this can only be solved by having the 2-stage build I was talking about earlier.
- Generate needs.json / intersphinx inventories for all dependent projects while ignoring broken links.
- Exchange the files between projects
- Run the full builds of all participating projects
- Deploy the docs
Depending on the amount of project relations, that leads to more frequent full builds of all projects.
Btw, the stage 1 build is also related to namespace support and edge properties.
If Sphinx-Needs knows whether a link goes internal or external, a safe stage 1 build becomes possible.
We would not have to suppress dead link warnings.
Another thought: How would the integration repository know in which order to build the projects for case M? You would only get an acyclic Bazel build graph when introducing 2-stage builds.
There was a problem hiding this comment.
Can't integration just build stage 1 on all documentations, exchange json files, build stage 2 on all documentations?
By the way, we can easily differentiate external-need-links as they start with an uppercase letter (module prefix).
There was a problem hiding this comment.
Yes, that's possible. Somes notes:
- You can also have links between other documentations, not just between integration and its children
- What's the relation between integration and docs? Is that the repo we are talking about https://github.com/eclipse-score/reference_integration? I do not see docs in there. If integration just means, we are rebuilding and deploying all documentations, to be sure the backlinks are up-to-date, then it's clear. But I would assume a safe build system, which, on change, knows what to rebuild. Backlink dependencies are part of this. If a needs.json changes, then all dependent projects on this file have to be rebuild.
- We need to make sure the stage 1 needs.json outputs are reproducible.
- Sphinx-Needs does not know about the module prefixes after the import, so you cannot suppress warnings based on this. That means we cannot rely on the
-Wflag (which turns warnings into != 0 exit code).
There was a problem hiding this comment.
I only learned about the bazel-drives-sphinx proof-of-concept yesterday. It seems to overlap very well with this decision record. I see no conflicts and the diagram in the readme is essentially the same diagram as in this record (just set project 1 as baselibs, project 2 as com, and project 3 as integration).
Correct, reference_integration has no documentation at all currently. Here is a commit to add it but it assumes we decide for option S here.
Now, I don't see any disagreement in this thread, so I believe we can resolve it.
There was a problem hiding this comment.
I would say these are 2 different things. This DR states
The S-CORE project adopted a multi-repo strategy. Since S-CORE aims for compliance with regulations like ASPICE, bi-directional traceability is necessary (see gd_req__req_traceability) and should be made convenient. How to provide this in S-CORE documentation?
The wanted bi-directional traceability in this context means backlinks. So the dependency is still unidirectional, but we want the HTML output to be aware of the opposite direction of links. I do not really like the term bi-directional traceability as it implies the dependency direction is bidirectional. It's not. I think backlinks is clearer. From build system point of view, if we have a 2-stage build, the bidirectionality is resolved which leads to a proper build DAG.
The bazel-drives-sphinx approach on the other end cares for file based traceability with Sphinx/Sphinx-Needs and a better integration to build systems (dependency management, caching). The goal is quick traceability that integrates well with possibly slower documentation builds. The approach can be adopted with or without backlinks.
The main question is whether we are accepting that some deployed versions of the build has incomplete backlinks, then we can run a softer version and not regenerate docs constantly. It also means any schema validation / traceability statement that must exist fast, cannot rely on backlinks being available.
There was a problem hiding this comment.
The term "bi-directional traceability" is used by ASPICE and an important keyphrase for many people in automotive.
This decision simply assumes that we accept "that some deployed versions of the build has incomplete backlinks". It says so in the goals section: "during development slight inconsistencies are acceptable." So far, nobody has questioned this assumption. Most importantly, our colleagues from the process community did not question it.
@FScholPer note that you can use different commands for exactly those two use cases... which we did not document.... hups. Commands:
|
|
Option S is the old option 1.1? Those old options mention some pros and cons that are missing in this DR? I guess that old DR is actually valid. As it states we'll implement option 2 (done), and then evaluate switching to option 1 (now) 😆 |
Yes, probably.
The "Shared navigation menu and search functionality" is "UX" here. The "No customization via conf.py, limiting module-specific templates" I'm not sure. Some customization is certainly possible. Some things are not but our process and docs-as-code toolchain already introduce limitations too and I'm not sure if that would limit it further.
The use cases are implicitly mentioned here. I don't think the constraints are necessary for the decision making here because they are too fundamental. Conciseness is important.
Neither option S nor M prevents anything about this. |
|
Pro S: simpler to implement (IMHO) -> Would it make sense to start with S and investigate M once we hit performance problems? Or offer both possibilities? |
AlexanderLanin
left a comment
AlexanderLanin
left a comment
There was a problem hiding this comment.
I think we've discussed all the mentioned points. If someone comes up with a POC we would be happy to look into option M. But until then S seems more feasable.
There was a problem hiding this comment.
Pull Request Overview
This PR introduces a design decision document (DR-004-Infra) that addresses bi-directional traceability in S-CORE documentation across multiple repositories. The document proposes a single documentation build approach to enable consistent backlinking and traceability required for compliance with regulations like ASPICE.
- Adds DR-004-Infra design decision document in RST format
- Includes two supporting diagrams showing module relationships and backlinking dependencies
- Evaluates two options (single build vs. module rebuild) for handling multi-repo documentation
Reviewed Changes
Copilot reviewed 1 out of 3 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| docs/design_decisions/DR-004-infra.rst | New design decision document proposing single documentation build strategy for bi-directional traceability |
| docs/design_decisions/img/DR-004-example.png | Diagram illustrating S-CORE module subset used as example |
| docs/design_decisions/img/DR-004-backlinking.png | Diagram showing module vs target dependencies for backlinking |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| Module vs Target dependencies | ||
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
There was a problem hiding this comment.
[nitpick] Corrected spelling of 'vs' to 'vs.' - abbreviations should include a period for consistency with formal documentation standards.
| Module vs Target dependencies | |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| Module vs. Target dependencies | |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
|
|
||
| The S-CORE project adopted a multi-repo strategy. | ||
| Since `S-CORE aims for compliance with regulations like ASPICE <https://eclipse-score.github.io/process_description/main/standards/index.html#standards>`_, | ||
| bi-directional traceability is necessary (see ``gd_req__req_traceability``) and should be made convenient. |
There was a problem hiding this comment.
The reference gd_req__req_traceability appears to be a needs-element ID but lacks context about where this requirement is defined. Consider adding a brief explanation or link to help readers understand this reference.
| bi-directional traceability is necessary (see ``gd_req__req_traceability``) and should be made convenient. | |
| bi-directional traceability is necessary (see `gd_req__req_traceability <https://eclipse-score.github.io/requirements/main/requirements.html#gd_req__req_traceability>`_) and should be made convenient. |
|
|
||
| 💚 Effort: Proof-of-concepts exist, so the basic implementation should be quick. | ||
|
|
||
| 😡 Bureaucracy: Modules must not use prefixes for external needs because it breaks the integration build. |
There was a problem hiding this comment.
[nitpick] Consider using 'cannot' instead of 'must not' for clarity. 'Must not' implies a prohibition, while 'cannot' indicates a technical limitation.
| 😡 Bureaucracy: Modules must not use prefixes for external needs because it breaks the integration build. | |
| 😡 Bureaucracy: Modules cannot use prefixes for external needs because it breaks the integration build. |
| The docs-as-code repo must be refactored accordingly. | ||
| Since the id schemas already contain namespacing rules, there is barely any risk of id clashes. | ||
|
|
||
| 😡 Speed: This will result a long-running build step unsuitable for pull requests in general. |
There was a problem hiding this comment.
Missing preposition 'in' - should be 'result in a long-running build step'.
| 😡 Speed: This will result a long-running build step unsuitable for pull requests in general. | |
| 😡 Speed: This will result in a long-running build step unsuitable for pull requests in general. |
|
We did not cover images correctly in CODEWNER. Can someone approve this please? |
7 participants
Rendered HTML: https://eclipse-score.github.io/score/pr-1930/design_decisions/DR-004-infra.html