EPIC: Create OCM CLI / Lib Developer Documentation

[In-Ko]

Description In order to provide ongoing support for the OCM CLI / Lib, it is crucial to have a decent developer documentation for it that allows new developers to onboard to the project quickly. This developer documentation (!= end user documentation) must explain:

• What the architecture looks like, including a visual architecture representation
• How the codebase is structured
• What developers have to do in order to setup their local environment / laptop to work on the OCM CLI Code
• How the release process (for the OCM CLI) is set up, e.g., a fix has to be provided. What is the branch setup for release and fixes, how is the test suite triggered upon PR-merge to main, etc.)

The complete documentation must enable developers to quickly understand the setup of the project in order to contribute to it, provide enhancements and fixes without having to consult the core maintainers.

The documentation should be accessible using a single, central document. If content is available in separated documents and for certain reasons should not be merged or moved into the central document, e.g. the "tour" that is part of the examples, it should always be linked in the central document. There SHOULD NOT be any documentation inside the repository that is not accessible from the central documentation, but just "stand-alone".

Definition of Done:

• [ ] There is a single, central documentation for developers available in the ocm repository.
• [ ] The documentation includes examples and use cases that supports new developers in understanding basic concepts of the current implementation of OCM.
• [ ] The documentation is easy to understand and avoids academic style.
• [ ] The revised documentation has been reviewed and validated by the target group for clarity and usability.

[jensh007]

I guess topics 1-3 are identical for OCM library and CLI or would there be anything different for the CLI?

[morri-son]

@fabianburth @mandelsoft @hilmarf @frewilhelm , maybe this is already present at various places, then we can close the issue quickly.

[frewilhelm]

I am pretty sure that "How the OCM CLI codebase is structured" is missing since the last restructuring as well as "How the release process for the OCM CLI is setup" because we have a meeting tomorrow on this topic^^.

[morri-son]

I am pretty sure that "How the OCM CLI codebase is structured" is missing since the last restructuring as well as "How the release process for the OCM CLI is setup" because we have a meeting tomorrow on this topic^^.

that's why I touched this issue again. It is part of the epic https://github.com/open-component-model/ocm-project/issues/161 which contains some issues that I also think we need to dig into soon. Looking at the plans to roll out OCM SAP internally, the focus should lie on end user documentation...