Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

EPIC: Create OCM CLI / Lib Developer Documentation #124

Open
4 tasks
Tracked by #161
In-Ko opened this issue Jun 26, 2023 · 4 comments
Open
4 tasks
Tracked by #161

EPIC: Create OCM CLI / Lib Developer Documentation #124

In-Ko opened this issue Jun 26, 2023 · 4 comments
Labels
area/documentation Documentation related area/ipcei Important Project of Common European Interest component/ocm-cli OCM Command Line Interface kind/epic Large multi-story topic
Milestone

Comments

@In-Ko
Copy link
Member

In-Ko commented Jun 26, 2023

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
Copy link

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

@morri-son morri-son added the area/ipcei Important Project of Common European Interest label Feb 6, 2024
@morri-son morri-son transferred this issue from open-component-model/ocm Mar 17, 2024
@morri-son morri-son added the component/ocm-cli OCM Command Line Interface label Mar 17, 2024
@morri-son morri-son added this to the 2024-Q4 milestone Sep 17, 2024
@morri-son
Copy link
Contributor

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

@frewilhelm
Copy link

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
Copy link
Contributor

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 #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...

@morri-son morri-son changed the title Create OCM CLI Developer Documentation Create OCM CLI / Lib Developer Documentation Oct 18, 2024
@morri-son morri-son added the kind/epic Large multi-story topic label Oct 22, 2024
@morri-son morri-son changed the title Create OCM CLI / Lib Developer Documentation EPIC: Create OCM CLI / Lib Developer Documentation Oct 22, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area/documentation Documentation related area/ipcei Important Project of Common European Interest component/ocm-cli OCM Command Line Interface kind/epic Large multi-story topic
Projects
Status: 🆕 ToDo
Development

No branches or pull requests

4 participants