DR: multi-repo setup #263
DR: multi-repo setup #263
Conversation
Co-authored-by: Maximilian Sören Pollak <[email protected]>
AlexanderLanin
requested review from
ltekieli,
nradakovic,
antonkri,
MaximilianSoerenPollak,
PhilipPartsch and
hoe-jo
AlexanderLanin
added
infrastructure
There was a problem hiding this comment.
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 maingets updated, most module-repos are not checked out- Single module-repo gets updated,
SCORE mainmay be locally outdated SCORE mainand 1 module-repo gets updated (new feature docs + implementation)- Finally these changes get committed by 2 PRs. The
SCORE mainPR 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.
- Finally these changes get committed by 2 PRs. The
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 :)
| * Good performance (no need to build all repositories at once) | ||
| Con: | ||
| * needs.json and the entire website needs to be hosted in multiple versions. | ||
| * bidirectional links affect the "core score" repository, which is not desired. |
There was a problem hiding this comment.
I don't understand this point by 100%: What exactly is affected in the "core score" repository?
From my understanding changes in the repository itself are not needed, just the final documentation gets incoming links from module-repos/docs.
There was a problem hiding this comment.
Yes, I was talking about the website, not the repository. Fixed:
bidirectional links affect the score-website, which is not desired
|
|
||
| Con: | ||
| * Relies heavily on bazel -> potential problems with esbonio etc | ||
| * Performance / runtime |
There was a problem hiding this comment.
This problem can be huge, depending on the content of the docs.
For instance, if each module-repo needs a doxygen/doxysphinx build for API -documentation.
It may be okay for a CI build, but giving the user feedback during editing (esbonio build) would take too long.
Maybe a 2-way approach/support would be good:
- A "complete" build for the CI and the deployed documentation
- A local quick & dirty build for the specific repo only, in which the current change gets implemented (for quick user feedback of ~95% of our checks/rules.)
There was a problem hiding this comment.
Puh... when we consider doxysphinx or similar solutions, then copying is probably completely out of the question.
review findings
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.
Closes #218