SUPER-EPIC: Increase OCM Maintainability and Contributability

[In-Ko]

Description

Based on various feedback both from endusers and developers, it is clear to see that the Project needs to improve in several areas to make it simpler for others to

1. Work with OCM ( = using existing clients and controllers, understanding the spec, running through tutorials/examples)
2. Contribute to OCM ( = understanding architectures of OCM CLI, OCM GO Library, OCM Controllers, MPAS System, using the GO Library to implement new clients)

It has been agreed that a workshop will be done, in order to identify the most critical areas for improvement in both areas (1) and (2). Based on this workshop, this Epic will be updated/enhanced.

1. Usability of OCM Library and Tooling

Feedback the Project received so far from various users / stakeholders / developers in this area:

• OCM CLI complicated to use and understand. Documentation not sufficient. More "easy to follow" examples and tutorials required.
• OCM Specification still very complex, hard to understand and navigate. Example: Is it really a good place to have a very technical description of the so-called "Model Elements" right here: https://github.com/open-component-model/ocm-spec/blob/main/doc/specification/README.md ?
• The OCM and MPAS Controllers also seem mostly undocumented. Endusers need to find information about: How to deploy/use these controllers ? What are their APIs ? What do they do / are they used for ? Ideally, these documentations are not separate files, but are (at least within an overview) are described together.

2. Contribute to OCM

Feedback the Project received so far from various users / stakeholders / developers in this area:

• A general "In which areas can Contributors help the OCM Project ?" Overview is missing. We have to guide developers to the right places where they find all necessary information/documentation for the existing clients / libraries / controllers. They need to know where to start if they want to create a new client with the GO Library, create a new controller or enhance an existing client.
• OCM GO Library incredibly hard to understand, very generic, no overview architecture or documentation available. Same is true for the OCM CLI. This makes it very hard for other developers to actually contribute to the Project.
• The OCM and MPAS Controllers also need more developer documentations and architecture descriptions.

Related Tasks

- Documentation Related

moved to own EPIC: #161

- OCM Library related

• Replace docker lib dealing with OCI Artifacts in OCI registries (ORAS client?) #106
• Improve error handling inside OCM library #102
• EPIC: Dependency Handling for a distributed project setup #100
• Better discoverability for public API usage #44
• EPIC: Restructure OCM library #27 (own EPIC)
• Simplify usage and References to various Context Interfaces ocm#913

- CLI related

• Improve OCM CLI using upstream cobra library #107
• Simplify and Refactor the OCM CLI Project Structure ocm#430
• EPIC: Automated Testing for OCM CLI #103
• EPIC: Dependency Handling for a distributed project setup #100

- OCM Controllers related

• Improve Dangling Resource Cleanup Strategy and Configuration Linting #77

- VSCode related

• Setup VSCode Extension Project vscode-ocm-tools#1 (example: update/remove)

- Community engagegement

• Improve Community engagement #86

Done Criteria

• All subtasks from above are done
• Successful demonstration/discussion in Review

[morri-son]

close as (sub-) epics exist. The issues will stay as they are, but not related to an EPIC.