add design decision for break cyclic repository between docs-as-code and process #2499
Conversation
RolandJentschETAS
requested review from
AlexanderLanin,
MaximilianSoerenPollak,
PandaeDo,
aschemmel-tech,
dcalavrezo-qorix,
masc2023 and
pahmann
as code owners
|
|
RolandJentschETAS
force-pushed
the
dr_007_docs_as_code_repo_independence
branch
from
38f4bbc to
e6d9fa3
Compare
|
The created documentation from the pull request is available at: docu-html |
| Goals and Requirements | ||
| ^^^^^^^^^^^^^^^^^^^^^^ | ||
|
|
||
| - Avoid cyclic dependencies between repositories. |
There was a problem hiding this comment.
This is a nice principle but not really a goal to pursue here.
There was a problem hiding this comment.
Avoiding cyclic dependencies is the reason for the current design decision. It makes it currently complicated to update the meta model. So it is really the goal.
| ^^^^^^^^^^^^^^^^^^^^^^ | ||
|
|
||
| - Avoid cyclic dependencies between repositories. | ||
| - Enable independent evolution of process requirements and meta model definitions. |
There was a problem hiding this comment.
This is already possible. Changing the process requirements does not implicitly change the metamodel implemented in docs-as-code.
Maybe you meant:
| - Enable independent evolution of process requirements and meta model definitions. | |
| - Enable independent evolution of templates in process description and docs-as-code meta model definitions. |
There was a problem hiding this comment.
As described above, the docs as code repo imports the sphinx needs elements of the examples while defining the meta model for them. So any change of the meta model from docs as code breaks the build of docs-as-code repo. Therefore the meta model could not be changed. Vice versa the process repo examples can't be changed, as long as the meta model is not changed. Because of this cyclic dependency changing the meta model is complicated and only possible in a multi step appoach.
|
|
||
| Option 2: Move meta model definition to process repository | ||
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
| Define and maintain the Sphinx-Needs meta model solely in the process repository. The docs-as-code repository would then only provide the infrastructure for the meta model, not define or modify it. The process repository would be the authoritative source for the meta model. Also tests and examples would be maintained there. |
There was a problem hiding this comment.
By "Sphinx-Needs meta model" we mostly think of the metamodel.yaml file. That would indeed be a nice abstraction but it is not the complete implementation. Some checks are implemented in Python. Example: https://github.com/eclipse-score/docs-as-code/blob/main/src/extensions/score_metamodel/checks/check_options.py#L150
So I assume this would mean to move the "score_metamodel" extension to process_description repository. That certainly would not be "low effort".
There was a problem hiding this comment.
- 1 part of score_metamodel is generic - we keep that in docs-as-code
- 1 part of score_metamodel is score specific python code - that is stuck in docs-as-code, and we live with it. It's a small part.
- 1 part of score_metamodel goes to process (yml)
- 1 part of score_metamodel is quite a bunch of examples (rst files). Most of these should go to process. But I feel this is already details if & after we decide for option 2.
| Flexibility, 💚, 💚, 😐, 💚 | ||
| Independence, 😐, 💚, 💚, 💚 | ||
| Maintainability, 💚, 💚, 😐, 💚 | ||
| Scalability, 😐, 😐, 😡, 💚 |
There was a problem hiding this comment.
I feel like option 1 and 2 are actually very similar, so I don't understand how this tables evaluates them differently with respect to Bureaucracy, Speed, and Independence.
There was a problem hiding this comment.
I have added a description for the options as well as for the evaluation. And also rework the evaluation with my best guesses. Hope thats fine now.
There was a problem hiding this comment.
Is "examples" and "templates" synonymous? If yes, we should only use one the terms. If no, define them properly.
There was a problem hiding this comment.
templates is a repository
|
Co-authored-by: Andreas Zwinkau <95761648+a-zw@users.noreply.github.com> Signed-off-by: RolandJentschETAS <135332348+RolandJentschETAS@users.noreply.github.com>
|
|
||
| Option 2: Move meta model definition to process repository | ||
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
| Define and maintain the Sphinx-Needs meta model solely in the process repository. The docs-as-code repository would then only provide the infrastructure for the meta model, not define or modify it. The process repository would be the authoritative source for the meta model. Also tests and examples would be maintained there. |
There was a problem hiding this comment.
- 1 part of score_metamodel is generic - we keep that in docs-as-code
- 1 part of score_metamodel is score specific python code - that is stuck in docs-as-code, and we live with it. It's a small part.
- 1 part of score_metamodel goes to process (yml)
- 1 part of score_metamodel is quite a bunch of examples (rst files). Most of these should go to process. But I feel this is already details if & after we decide for option 2.
|
|
||
| Option 3: Move examples (Sphinx-Needs objects) to a third repository | ||
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
| Extract all example Sphinx-Needs objects (currently imported into docs-as-code) into a separate third repository. The process repository will become independent and docs-as-code repositories would depend on this third repository for examples, breaking the cyclic dependency. But this adds complexity with an additional repository to maintain and still contains cyclic dependencies between all three repositories. |
There was a problem hiding this comment.
That's confusing. You are talking about examples in process?
Cyclic dependency is described in problem statement.
(You could also repeat it, but "currently imported into docs-as-code" is confusing as-is)
| Extract all example Sphinx-Needs objects (currently imported into docs-as-code) into a separate third repository. The process repository will become independent and docs-as-code repositories would depend on this third repository for examples, breaking the cyclic dependency. But this adds complexity with an additional repository to maintain and still contains cyclic dependencies between all three repositories. | |
| Extract all example Sphinx-Needs objects (currently in process_description) into a separate third repository. The process repository will become independent and docs-as-code repositories would depend on this third repository for examples, breaking the cyclic dependency. But this adds complexity with an additional repository to maintain and still contains cyclic dependencies between all three repositories. |
|
|
||
| Option 4: Move meta model and examples into a separate repository | ||
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
| Create or use a dedicated meta model repository that contains only the Sphinx-Needs meta model definitions and the examples. Both the process repository and docs-as-code repository would depend on this meta model repository (if necessary), making it the single source of truth. This breaks the cycle by introducing a clear hierarchical dependency structure. |
There was a problem hiding this comment.
From an architecture point of view this is rather nice, so lets mention it.
| Create or use a dedicated meta model repository that contains only the Sphinx-Needs meta model definitions and the examples. Both the process repository and docs-as-code repository would depend on this meta model repository (if necessary), making it the single source of truth. This breaks the cycle by introducing a clear hierarchical dependency structure. | |
| Create or use a dedicated meta model repository that contains only the Sphinx-Needs meta model definitions and the examples. Both the process repository and docs-as-code repository would depend on this meta model repository (if necessary), making it the single source of truth. This breaks the cycle by introducing a clear hierarchical dependency structure. | |
| Process repository becomes more docs-as-code independent. And docs-as-code becomes more score-independent. |
| :header: Criteria, Option 0, Option 1, Option 2, Option 3, Option 4, Option 5, Option 6 | ||
| :widths: 20, 10, 10, 10, 10, 10, 10, 10 | ||
|
|
||
| Effort,Speed 💚, 😡, 😐, 😐, 😡, 💚, 💚 |
There was a problem hiding this comment.
I think effort for 2 and 4 are rather identical: 😡
Effort for 3 and 5 should be identical? I'm guessing 😐? Repo setup is <1h.
| Effort,Speed 💚, 😡, 😐, 😐, 😡, 💚, 💚 | |
| Effort 💚, 😐, 😡, 😐, 😡, 😐, 💚 |
| :widths: 20, 10, 10, 10, 10, 10, 10, 10 | ||
|
|
||
| Effort,Speed 💚, 😡, 😐, 😐, 😡, 💚, 💚 | ||
| Speed, 💚, 😐, 😐, 😡, 😡, 💚, 💚 |
There was a problem hiding this comment.
I have no idea how to review Speed? What's the difference with effort? Overall rollout? But isn't that handled in effort already?
|
|
||
| Effort,Speed 💚, 😡, 😐, 😐, 😡, 💚, 💚 | ||
| Speed, 💚, 😐, 😐, 😡, 😡, 💚, 💚 | ||
| UX, 😡, 💚, 💚, 😡, 💚, 💚, 😐 |
There was a problem hiding this comment.
UX includes keeping requirements, metamodel and examples in sync? Regardless of administrative overhead, this is complex across repositories.
| UX, 😡, 💚, 💚, 😡, 💚, 💚, 😐 | |
| UX, 😡, 💚, 💚, 😡, 😐, 😐, 😐 |
| Effort,Speed 💚, 😡, 😐, 😐, 😡, 💚, 💚 | ||
| Speed, 💚, 😐, 😐, 😡, 😡, 💚, 💚 | ||
| UX, 😡, 💚, 💚, 😡, 💚, 💚, 😐 | ||
| Bureaucracy, 😐, 💚, 😐, 😡, 😡, 😐, 😐 |
There was a problem hiding this comment.
Oh ok, we have Bureaucracy for what I just mentioned in UX. For me personally UX and Bureaucracy are one and the same?! I don't know how to consider UX without Bureaucracy. In order to work on the metamodel / examples, you need matching requirements.
| Speed, 💚, 😐, 😐, 😡, 😡, 💚, 💚 | ||
| UX, 😡, 💚, 💚, 😡, 💚, 💚, 😐 | ||
| Bureaucracy, 😐, 💚, 😐, 😡, 😡, 😐, 😐 | ||
| Flexibility, 😡, 💚, 💚, 😐, 💚, 💚, 😐 |
There was a problem hiding this comment.
Sorry, I dont get what this is. Is that like extendibility with future docs-as-code features?
| UX, 😡, 💚, 💚, 😡, 💚, 💚, 😐 | ||
| Bureaucracy, 😐, 💚, 😐, 😡, 😡, 😐, 😐 | ||
| Flexibility, 😡, 💚, 💚, 😐, 💚, 💚, 😐 | ||
| Independence, 😐, 😐, 😐, 💚, 💚, 💚, 😐 |
There was a problem hiding this comment.
independence of whom with whom? Isn't independence exactly what we want to avoid?
|
|
||
| **Rationale:** | ||
|
|
||
| - **Option 0 (No change)**: No effort required, poor UX (frequent build failures), low bureaucracy (current process), immediate (no implementation needed), poor flexibility (locked into current structure), poor independence (cyclic dependency remains), poor maintainability (ongoing coordination burden), poor scalability (problem worsens as repos grow). |
There was a problem hiding this comment.
Having smileys above and every smiley explained here doesn't work. If these explanations add value, they must be directly in the table. It's super hard to find the explanation of each smiley here.
There was a problem hiding this comment.
The approach I use is to have the explanations with the options. This keeps the table lean.
If an explanation about the criteria themselves (independent of the options) is needed, then this should be done in the "Context / Problem" section. Maybe there should even be a 1:1 relation between the goals and the criteria.
|
|
||
| Option 0 scores poorly with respect to independence, UX, and maintainability. | ||
| Option 1 requires high effort. | ||
| Option 6 compromises maintainability. |
There was a problem hiding this comment.
Option 5 looks just a good as option 2 and there is not reason documented why option 2 is selected instead.
aschemmel-tech
left a comment
aschemmel-tech
left a comment
There was a problem hiding this comment.
Like discussed in the process community, I am also fine with selection of option 2.
4 participants
Add design decision for break cyclic repository between docs-as-code and process repository
Rendered: https://eclipse-score.github.io/score/pr-2499/design_decisions/DR-007-infra.html