add design decision for break cyclic dependency between docs-as-code and process repository #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 |
|
Co-authored-by: Andreas Zwinkau <[email protected]> Signed-off-by: RolandJentschETAS <[email protected]>
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.
| Option 6 compromises maintainability. | ||
|
|
||
| **Decision:** Option 2 or Option 5 both provide the same benefits but Option 5 requires less effort, so we pick it. | ||
| **Decision:** Option 5 is obviously the best choice. |
There was a problem hiding this comment.
See here, was also presented and discussed
https://github.com/orgs/eclipse-score/discussions/407#discussioncomment-15605348
Option 2 was preferred as it would give independence in the form, that process_description could be used also with other tools, or doc-as-code could even use other models, is that reflected here?
There was a problem hiding this comment.
Independence is actually slightly better with Option 5 hence the 💛 vs 💚 difference. Option 2 provides independence but requires process_description to specify the meta model "in full detail". For contrast, with Option 5 only vague textual requirements are needed.
Both, Option 2 and 5 would allow for alternative tools (like TLRC).
a-zw
force-pushed
the
dr_007_docs_as_code_repo_independence
branch
from
2944d89 to
9e16555
Compare
RolandJentschETAS
changed the title
RolandJentschETAS
changed the title
Now option 3 is the winner.
a-zw
force-pushed
the
dr_007_docs_as_code_repo_independence
branch
from
4a96413 to
d947f9a
Compare
|
Now option 3 wins: Move examples to module_template repository |
aschemmel-tech
left a comment
aschemmel-tech
left a comment
There was a problem hiding this comment.
Agree to Option 3 as in discussion. One documentation issue stated inline.
|
|
||
| Extract all example Sphinx-Needs objects (currently imported into docs-as-code) into ``module_template``. | ||
| The process repository is 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.
My impression from the discussion was not that this solution "still contains cyclic dependencies between all three repositories"
There was a problem hiding this comment.
Good catch. That is outdated text which I forgot to update.
Move the templates to module_template right? |
Yes, that was discussed, examples in doc-as-code, templates for the modules into module_templates, may high-level templates stay in process_description, but they are very stable |
Also, fix a few minor misunderstandings.
…as-code and process repository (#2499) Co-authored-by: Andreas Zwinkau <[email protected]>
6 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