DR-008-infra first draft

[a-zw]

Rendered: https://eclipse-score.github.io/score/pr-2615/design_decisions/DR-008-infra.html

[github-actions]

⚠️ Docs-as-Code version mismatch detected
Please check the CI build logs for details and align the documentation version with the Bazel dependency.

[github-actions]

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

[MaximilianSoerenPollak]

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. ?

[github-actions]

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

[a-zw]

@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".

[ramceb]

Its correct that one git repository contains in general one bazel module. But one bazel module can contain several dependable_elements. So a bazel module corresponds to a "Delivery container" as described in process description

[a-zw]

@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.

[ramceb]

I am fine with rewording this goal. What I want to say is that we should leverage the mechanisms of the build infrastructure to support adherence to the processes

[a-zw]

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.

[ramceb]

you are correct. We are addressing 2 points. Its just that the one (proper use of bazel) is a precondition for the other (supporting process adherence by means of bazel)

[a-zw]

How does the Module-API handle traceability to implementation and tests?

[ramceb]

The module_api concept foresees that each dependable element provides an API, where any user of the dependable element can obtain the information needed (e.g. traceability, assumptions_of_use, etc) to integrate the module in his system. The traceability information is calculated inside of the module as well as any documentation is generated. .
e.g. if you have define a dependable_element "foo" for your module.
Then you execute bazel build/test //:foo and the necessary artifacts e.g. coverage report, test report, etc will be provided by bazel either via test execution or documentation generation.