DR: multi-repo setup

[AlexanderLanin]

Dear bazel and docs-as-code people: please review the entire DR.

All other stakeholders (e.g. process experts) should focus on reviewing the use cases / requirements and constraints.

Readable version: https://github.com/AlexanderLanin/score/blob/docs-multirepo/docs/_tooling/decision-records/multirepo.md

Closes #218

[danwos]

Thanks for the great write-up.

I don't have a strong opinion about the different solutions.

Regarding the proposed solution "Copying", I just asked myself, how this works in the different scenarios for local builds:

• SCORE main gets updated, most module-repos are not checked out
• Single module-repo gets updated, SCORE main may be locally outdated
• SCORE main and 1 module-repo gets updated (new feature docs + implementation)
  • Finally these changes get committed by 2 PRs. The SCORE main PR needs to be merged first so that the module-PR can use a valid feature as a link target. Doable, and maybe not a common use case.

For fast, local feedback it should be possible to build the docs with SCORE main and one selected module-repo only.
Do you think this is possible? I'm a bazel newbie, so I'm unsure :)

[AlexanderLanin]

Applying the meeting minutes was surprisingly trivial, as in the end we have simply picked solution 2 for all use cases.

Meeting-Minutes / Discussion Results

module build: solution 2 with improvements regarding tagged-constraint

• use tagged score/platform as external-needs
  Hint: via bazel we can get needs.json from source every time! bazel will use caching internally!
  (TODO: set up CI-cache)
  Alternatively from build artefacts, website etc as a release artefact
  Alternatively directly from gh-pages branch or website
  Note: this will require maintaining the docs:docs build!!!!! -> Lukasz, Max, Alex later!
• verify links and hashes
  • For tagged module builds only / for non-draft requirements only: ERROR
  • Otherwise: WARNING
• website has only uni-directional links to score/platform website ("quick" in DR)

(reference-) integration build:

We want bi-directional links => Multiple platform websites:

score.com/vXXX/platform
-> everything
-> no links

score.com/vXXX/integration-/platform
-> specific platform version (defined by bazel; tagged score/platform)
-> only enabled features in
-> links to all modules which are in integration-
(idea: use very different website background e.g. via different css file)

• same as modules: verify links and hashes
• For tagged builds only / for non-draft requirements only: ERROR
• Otherwise: WARNING

Start with uni-directional linking as in modules for the next weeks/months
Regardless of what the end goal is!

[github-actions]

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

[MaximilianSoerenPollak]

LGTM, just one comment regarding sentence understandability.

outdated

[github-actions]

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

[github-actions]

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

[github-actions]

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

[github-actions]

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

[AlexanderLanin]

Please have a look whether option 2 still is our favorite!
I've rewritten option 3 and added a summary.

@PhilipPartsch @MaximilianSoerenPollak @ltekieli @nradakovic @hoe-jo @danwos