Conversation
|
|
a-zw
force-pushed
the
dr-docs-modularity
branch
from
c37a5cc to
477afe9
Compare
|
The created documentation from the pull request is available at: docu-html |
|
Additional option here would be the current one. We keep the current Docs way and let the PoC exist in parallel but do not actively support it from docs-as-code/infra to not split our efforts. ? |
|
This PR is stale because it has been open for 30 days with no activity. It will be closed in 10 days if no further activity occurs. #magic___^_^___line |
| artifacts that clearly describe the content of a | ||
| dependable element | ||
| (`see process glossary <https://eclipse-score.github.io/process_description/main/glossary/index.html#terms>`_). | ||
| The existing documentation build concept does not properly support this. |
There was a problem hiding this comment.
@ramceb I'm not convinced that "The existing documentation build concept does not properly support this."
The current concept only has "a Bazel module" as reuseable element, so one per git repository. With option M, we can have any number of dependable elements. I don't see how that significantly improves the situation. Still "teams must manually structure documentation to match the S-CORE process".
| - **Proper support of S-CORE adoption**: Enable teams to structure their documentation | ||
| according to the S-CORE process, with dedicated artifact types for requirements, | ||
| architectural design, safety analysis, and assumptions of use. | ||
| - **Proper support of Bazel**: Ensure documentation builds adhere to Bazel's core |
There was a problem hiding this comment.
@ramceb I'm not happy with how this goal is phrased. It sounds like "don't ask what Bazel can do for you, instead ask what you can do for Bazel."
The real goals are rather "build correctness" or "reproducability" or "build speed". The means to achieve them are hermeticity, caching, parallelism, and Bazel does a great job providing the mechanisms.
| architectural design, safety analysis, and assumptions of use. | ||
| - **Proper support of Bazel**: Ensure documentation builds adhere to Bazel's core | ||
| principles — hermeticity, reproducibility, and correct dependency tracking — enabling | ||
| action caching, remote caching, remote execution, and parallel builds. |
There was a problem hiding this comment.
I'm not yet quite sure what this PR is about. If it is primarily about using bazel build (instead of bazel run), then we can have that much cheaper than option M. See the abandoned eclipse-score/docs-as-code#286.
However, if it is about having concepts like "dependable element" within Bazel, then aspects like hermeticity are missing the point.
While both questions are closely related, is it really the case that deciding one implies the other? If not, then we should have to separate decision. If yes, then we should explicitly select in the Goals section which one is more important.
| Assessment | ||
| ~~~~~~~~~~ | ||
|
|
||
| - **Proper support of S-CORE adoption** 💚 Purpose-built rules for each S-CORE |
There was a problem hiding this comment.
How does the Module-API handle traceability to implementation and tests?
And fix a link to point to HTML instead of RST source.
a-zw
force-pushed
the
dr-docs-modularity
branch
from
32d8b83 to
3b0f976
Compare
3 participants
Rendered: https://eclipse-score.github.io/score/pr-2615/design_decisions/DR-008-infra.html