Improve Open Component Model (OCM) Specification

[robertwol]

The OCM project aims to enhance the specification to make it more understandable, accessible, and user-friendly. This user story focuses on improving the OCM specification itself to provide clear explanations, simplify the language and structure, and enhance the overall documentation.

Related Tasks:

1. Review and refine the specification: Assess the existing specification and identify areas that require improvement. Simplify the language, remove unnecessary complexity, and ensure clarity throughout the spec.
2. Modularize: Break down the specification into smaller, focused documents with clear sections and cross-references. Create separate documents for different components or concepts within the OCM specification.
3. Visual aids and diagrams: Create visual aids, such as diagrams, flowcharts, and examples, to supplement the textual description. Use visuals to illustrate key concepts, relationships, and use cases.
4. Provide an overview and guiding structure: Introduce an overview section that provides a high-level explanation of the OCM specification. Define and explain terms such as "OCM Repository" to ensure a clear understanding among readers.

Subtasks: (breakdown if needed)

• Refine structure
• Review and refine the specification, simplify language
• Visual aids
• High level introduction
• Bump helm.sh/helm/v3 from 3.9.1 to 3.9.4 ocm#80

Done by

• fix list of access methods #61
• Add chapter structuring doc with ocm #53
• incorporate spec changes #56
• remove schemas from spec and refer to ocm repo instead #57
• Reword and move signing into the proposal section #24
• add npm access type #59
• Complete support for helm chart access and npm ocm#407

Definition of Done:

• The OCM specification has been reviewed and refined to improve understandability.
• The specification has been modularized into smaller, focused documents with clear sections and cross-references.
• Visual aids, such as diagrams and flowcharts, have been created and integrated into the spec.
• An overview section has been added to provide a high-level explanation of the OCM specification, including clear definitions of relevant terms.

[jensh007]

Some comments and questions:

• Can you elaborate what is meant with "has been modularized into smaller, focused documents". The specification consists of many smaller markdown documents linked and cross-referenced. What would you have in mind for better modularization? For me it is more the structure of the content which is debatable.
• step-by-step guides I do not agree on this point. Please keep specification and tutorials separated. We had this discussion in the past and intentionally removed the "scenarios" chapter. Specification is specification and tutorials are for sure important but belong to ocm-website. Please give more guidance what kind of guides are missing and what scenarios should be explained in detailed.
• An overview section has been added to provide a high-level explanation We have chapter 1 introduction. What do you have in mind here instead? I do not see any value in adding another overview chapter. We can rename introduction to overview but for me it is more about the content of this chapter that needs to be rephrased.

[Skarlso]

@shivenduverma-sap The spec and the controller's domain objects are two separate things. This issue is about the OCM spec under https://github.com/open-component-model/ocm-spec

[jensh007]

Proposal for changes:
Introduction

• omit first paragraph
• remove Why is this a huge problem?
• remove How can this improve?

Start with scope

Shorten component repositories, it contains a lot of unrelated text, focus on:

• what is it: a container to hold and persist component versions
• defined by a mapping (or layout?) on existing storage technologies, most prominently OCI
• concept of references between entities
• transport format (Component Bundle)
• focus on images and container deployments but not restricted to

Describe Use Cases:

• Transport
• Deployment/Installations
• Malware Scanning
• Auditing

Describe what it is not:

• a communication protocol like http
• a database like tool with a rich query interface
• a tool set

Typical Implementations:

• transport tool
• creation tool
• scan tool
• browsing tool

Shorten component version:

• describe relation component vs. component versions
• examples

Add section Component Descriptor

• yaml format
• describes a component version
• consists of metadata plus resources
• can reference other component versions
• can have origin (e.g. source repository)

Add examples section:

• one component, n versions
• source
• references
• add a diagram explaining the relationships.

[jensh007]

Proposed new structure

• remove chapters, introduction, scenarios, example, appendix

• make specification as root, merge appendix into specification

• Introduction

• Model (former Structure and Elements)

  • Component (Versions)
  • resources
    -- external
    -- local
    -- access methods
  • sources
  • signatures
  • labels
  • schemas (restrict on one version)
    -> Merge the "types" section into the former sections

• Persistence ("mappings") -> needs a better name
  -- OCI
  -- CTF
  -- S3?

• Operations

• Signing
  -- normalization
  -- algorithms (digests and signing algs)
  -- keyless signing

• Extensions
  -- custom artifact types
  ...

[jensh007]

Created a branch to work on the restructured spec.

[jensh007]

Added missing chapters, lots of rephrashing and removing redundancy
Following issues created:

open-component-model/ocm#62
open-component-model/ocm#63
open-component-model/ocm#64
open-component-model/ocm#65
open-component-model/ocm#66
open-component-model/ocm#67
open-component-model/ocm#68
open-component-model/ocm#69
open-component-model/ocm#70
open-component-model/ocm#71
open-component-model/ocm#72
open-component-model/ocm#73

[jensh007]

• Introduction added with diagram
• Feedback received and specification updated. Thank You@jkafka23 for review, feedback and additional contributions
• Critics received that there is no longer a clear separation between code model and extensions (Thanks @mandelsoft for reviewing)

[jensh007]

Added more issues:

open-component-model/ocm#74
open-component-model/ocm#76
open-component-model/ocm#77
open-component-model/ocm#78

Important: We need to agree on a procedure how to update the spec:

• No more uncontrolled enhancements to versions considered to be frozen
• Have a frozen version 0.x and a working-draft 0.x+1
• Have a defined way to release a new spec version
  • community consensus (majority vote, absolute majority, unanimous, ...) or just if no one objects
  • no more open issues (can be deferred to next version, but must have been reviewed)
  • somehow documented release decision (e.g. as issue)

[phoban01]

@jensh007 Added open-component-model/ocm#80 to track change management for spec.

[jensh007]

After a lot of positive feedback I suggest to merge the current state into main and to continue with open issues from there. For this I created a pull request open-component-model/ocm#89. Please vote on accepting this PR.

/vote-profileocm

[git-vote]

Vote created

@jensh007 has called for a vote on Improve Open Component Model (OCM) Specification (#60).

The members of the following teams have binding votes:

Team
@open-component-model/ocm-dev

Non-binding votes are also appreciated as a sign of support!

How to vote

You can cast your vote by reacting to this comment. The following reactions are supported:

In favor	Against	Abstain
👍	👎	👀

Please note that voting for multiple options is not allowed and those votes won't be counted.

The vote will be open for 5days. It will pass if at least 50% of the users with binding votes vote In favor 👍. Once it's closed, results will be published here as a new comment.

[git-vote]

Vote closed

The vote passed! 🎉

66.67% of the users with binding vote were in favor (passing threshold: 50%).

Summary

In favor	Against	Abstain	Not voted
6	0	0	3

Binding votes (6)

User	Vote	Timestamp
@jensh007	In favor	2023-10-13 6:30:43.0 +00:00:00
@phoban01	In favor	2023-10-16 9:26:37.0 +00:00:00
@morri-son	In favor	2023-10-13 8:11:46.0 +00:00:00
@shivenduverma-sap	In favor	2023-10-13 11:44:56.0 +00:00:00
@robertwol	In favor	2023-10-16 8:26:44.0 +00:00:00
@In-Ko	In favor	2023-10-13 9:46:07.0 +00:00:00

[morri-son]

Structure changes merged to main, several of the mentioned issues have been closed. A follow-up Epic has been created which contains the rest of open issues: open-component-model/ocm-project#137