Skip to content
This repository was archived by the owner on Apr 13, 2026. It is now read-only.

docs: add component authoring how-to guides#739

Merged
piotrjanik merged 2 commits into
open-component-model:mainfrom
piotrjanik:docs/889-component-authoring-documentation
Mar 20, 2026
Merged

docs: add component authoring how-to guides#739
piotrjanik merged 2 commits into
open-component-model:mainfrom
piotrjanik:docs/889-component-authoring-documentation

Conversation

@piotrjanik

@piotrjanik piotrjanik commented Mar 4, 2026

Copy link
Copy Markdown
Contributor

docs: add component authoring documentation

What this PR does / why we need it

Adds comprehensive documentation for component authoring with the new OCM CLI:

New reference pages:

  • reference/component-constructor.md — field reference for component-constructor.yaml, the input format for ocm add cv
  • reference/component-descriptor.md — field reference for the component descriptor output format (v2 schema)
  • reference/input-and-access-types.md — field-level reference for all supported input types (dir, file, helm/v1, utf8) and access types (OCIImage, localBlob, OCIImageLayer, Helm)

New how-to and tutorial:

  • how-to/model-products.md — step-by-step guide for modeling multi-component products with component references
  • tutorials/advanced-component-constructor.md — tutorial covering multi-component constructors, labels, sources, and nesting patterns

Replaced outdated content:

  • Removed tutorials/complex-component-structure-deployment.md (replaced by model-products.md)
  • Removed tutorials/component-descriptor-example.md (replaced by component-descriptor.md reference)
  • Moved and rewrote tutorials/input-and-access-types.md as a reference page, removing types not supported by the new OCM (binary, docker, dockermulti, ociImage, spiff, gitHub, npm, s3, wget)

Which issue(s) this PR fixes

Fixes: open-component-model/ocm-project#889

@piotrjanik piotrjanik requested a review from a team as a code owner March 4, 2026 23:24
@netlify

netlify Bot commented Mar 4, 2026

Copy link
Copy Markdown

Deploy Preview for open-component-model ready!

Name Link
🔨 Latest commit b7206e9
🔍 Latest deploy log https://app.netlify.com/projects/open-component-model/deploys/69bd13070ad2c90008a91ad0
😎 Deploy Preview https://deploy-preview-739--open-component-model.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@coderabbitai

coderabbitai Bot commented Mar 4, 2026

Copy link
Copy Markdown

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review
📝 Walkthrough

Walkthrough

Adds comprehensive Component Constructor and Component Descriptor reference pages, a how-to for modeling multi-component products, a detailed advanced tutorial, removes two obsolete tutorials, and updates navigation links to point to the new tutorial.

Changes

Cohort / File(s) Summary
New How-To
content/docs/how-to/model-products.md
Adds a how-to for modeling multi-component products using OCM component references, versioned BOMs, CTF export, and release bumping workflows.
New Tutorials
content/docs/tutorials/advanced-component-constructor.md
Adds a detailed tutorial demonstrating multi-level component constructor usage, examples for leaf/product/platform components, build/verify steps, parameterization, and expected outputs.
New Reference Docs
content/docs/reference/component-constructor.md, content/docs/reference/component-descriptor.md
Adds reference documentation for the Component Constructor YAML schema and the Open Component Model component descriptor format, including field definitions, access types, validation, and examples.
Removed Tutorials
content/docs/tutorials/component-descriptor-example.md, content/docs/tutorials/complex-component-structure-deployment.md
Deletes older tutorial/example pages that overlapped with the new how-to and tutorial content.
Navigation Updates
content/_index.md, content/docs/getting-started/deploy-helm-chart.md
Replaces links that previously pointed to complex-component-structure-deployment.md so they now reference the new advanced-component-constructor.md tutorial.

Sequence Diagram(s)

(omitted — changes are documentation-only and do not introduce new runtime control flows)

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

Suggested labels

area/documentation

Suggested reviewers

  • morri-son
  • matthiasbruns
  • jakobmoellerdev

Poem

🐰📚 I hopped through pages, made a trail,
Constructor maps and descriptors unveil,
Tutorials nested, links now aligned,
Products modeled, versions pinned in kind,
A joyous hop — docs neat and hale! 🥕✨

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title 'docs: add component authoring how-to guides' accurately summarizes the main changes: three new how-to guides for component authoring.
Linked Issues check ✅ Passed The PR successfully implements the core coding objectives from #889: new how-to guides for constructor and product modeling, reference documentation, and updated cross-references to the new guides.
Out of Scope Changes check ✅ Passed All changes align with #889 scope: new how-to guides, reference docs, replacement of old tutorial, and updates to cross-references. No unrelated changes present.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
📝 Coding Plan
  • Generate coding plan for human review comments

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@piotrjanik piotrjanik force-pushed the docs/889-component-authoring-documentation branch from 88bf72c to 4df70b9 Compare March 4, 2026 23:28

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@content/docs/how-to/model-products.md`:
- Around line 153-161: The phrase "all three components plus the aggregator" is
misleading because the example table shows only three entries; update the
wording near the verification output (the sentence referencing "all three
components plus the aggregator" or similar text) to explicitly list or rephrase
to "backend, frontend, and the aggregator component" (or "three components
including the aggregator") so it matches the example table header "COMPONENT │
VERSION │ PROVIDER" and the shown entries.

In `@content/docs/how-to/use-component-constructor.md`:
- Around line 355-357: Update the example shell snippet that sets VERSION and
IMAGE_VERSION so the command is executable by adding the repository target;
change the command using the existing symbols (VERSION, IMAGE_VERSION and the
command invocation `ocm add cv`) to include the same repository flag used
earlier (e.g., `--repository ./transport-archive`) so the snippet runs as shown.
- Around line 186-190: Replace the incorrect artifact type casing "fileSystem"
with the canonical lowercase "filesystem" in this document; locate the two
occurrences where the YAML block contains "type: fileSystem" (the same blocks
that include "input:" and "type: dir/v1") and update them to "type: filesystem"
so all artifact type entries match the OCM specification.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 407db11a-5204-4f44-828e-5f1bd3c87e15

📥 Commits

Reviewing files that changed from the base of the PR and between 9a45df4 and 88bf72c.

📒 Files selected for processing (4)
  • content/docs/how-to/inspect-component-descriptor.md
  • content/docs/how-to/model-products.md
  • content/docs/how-to/use-component-constructor.md
  • content/docs/tutorials/component-descriptor-example.md
💤 Files with no reviewable changes (1)
  • content/docs/tutorials/component-descriptor-example.md

Comment thread content/docs/how-to/model-products.md Outdated
Comment thread content/docs/how-to/use-component-constructor.md Outdated
Comment thread content/docs/how-to/use-component-constructor.md Outdated

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

♻️ Duplicate comments (2)
content/docs/how-to/use-component-constructor.md (2)

356-356: ⚠️ Potential issue | 🟡 Minor

Make the env-var command runnable in-place.

Line 356 omits the repository target used elsewhere in this guide. Add --repository ./transport-archive so readers can execute the snippet directly.

Suggested fix
-VERSION=1.2.3 IMAGE_VERSION=6.9.4 ocm add cv
+VERSION=1.2.3 IMAGE_VERSION=6.9.4 ocm add cv --repository ./transport-archive
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@content/docs/how-to/use-component-constructor.md` at line 356, The env-var
command shown ("VERSION=1.2.3 IMAGE_VERSION=6.9.4 ocm add cv") is missing the
repository target; update that snippet to include the repository flag so it is
runnable in-place by changing it to "VERSION=1.2.3 IMAGE_VERSION=6.9.4 ocm add
cv --repository ./transport-archive".

86-86: ⚠️ Potential issue | 🟠 Major

Use a single canonical artifact type name (filesystem) in examples.

Line 86 and Line 278 use type: fileSystem, while Line 186 and Line 304 use type: filesystem. Please standardize on filesystem to avoid invalid/ambiguous constructor examples.

#!/bin/bash
set -euo pipefail

echo "Checking inconsistent filesystem type casing in constructor guide..."
rg -n -C1 'type:\s*(fileSystem|filesystem)' content/docs/how-to/use-component-constructor.md

Also applies to: 278-278

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@content/docs/how-to/use-component-constructor.md` at line 86, Several
examples use inconsistent casing for the artifact type (some use "type:
fileSystem" while others use "type: filesystem"); update all occurrences of the
artifact type to the canonical lowercase "filesystem" (replace the literal
strings "type: fileSystem" at the example instances with "type: filesystem" so
the constructor examples are consistent and valid) and double-check other
example blocks for any remaining "fileSystem" variants.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@content/docs/how-to/use-component-constructor.md`:
- Line 52: Update the tip text that currently reads “The `#yaml-language-server`
comment enables auto-completion and inline validation in editors that support
the YAML Language Server.” Replace the redundant phrase “YAML Language Server”
with a tightened alternative such as “YAML Server” or “YAML support” and ensure
the sentence still references the `#yaml-language-server` comment and the schema
URL at ocm.software/schemas/configuration-schema.yaml so editors and schema info
remain clear.

---

Duplicate comments:
In `@content/docs/how-to/use-component-constructor.md`:
- Line 356: The env-var command shown ("VERSION=1.2.3 IMAGE_VERSION=6.9.4 ocm
add cv") is missing the repository target; update that snippet to include the
repository flag so it is runnable in-place by changing it to "VERSION=1.2.3
IMAGE_VERSION=6.9.4 ocm add cv --repository ./transport-archive".
- Line 86: Several examples use inconsistent casing for the artifact type (some
use "type: fileSystem" while others use "type: filesystem"); update all
occurrences of the artifact type to the canonical lowercase "filesystem"
(replace the literal strings "type: fileSystem" at the example instances with
"type: filesystem" so the constructor examples are consistent and valid) and
double-check other example blocks for any remaining "fileSystem" variants.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 82648b80-e9a5-4da5-aaf4-64dda2fe55c8

📥 Commits

Reviewing files that changed from the base of the PR and between 88bf72c and 4df70b9.

📒 Files selected for processing (5)
  • content/docs/getting-started/create-component-version.md
  • content/docs/how-to/inspect-component-descriptor.md
  • content/docs/how-to/model-products.md
  • content/docs/how-to/use-component-constructor.md
  • content/docs/tutorials/component-descriptor-example.md
💤 Files with no reviewable changes (1)
  • content/docs/tutorials/component-descriptor-example.md
✅ Files skipped from review due to trivial changes (1)
  • content/docs/getting-started/create-component-version.md
🚧 Files skipped from review as they are similar to previous changes (1)
  • content/docs/how-to/model-products.md

Comment thread content/docs/how-to/use-component-constructor.md Outdated
@piotrjanik piotrjanik force-pushed the docs/889-component-authoring-documentation branch from 4df70b9 to 01344f6 Compare March 5, 2026 17:29

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

♻️ Duplicate comments (2)
content/docs/how-to/use-component-constructor.md (2)

356-356: ⚠️ Potential issue | 🟡 Minor

Make the env-var command runnable in-place.

Line 356 omits the repository target used earlier in the guide. Add --repository ./transport-archive so this command is executable as shown.

Proposed fix
-VERSION=1.2.3 IMAGE_VERSION=6.9.4 ocm add cv
+VERSION=1.2.3 IMAGE_VERSION=6.9.4 ocm add cv --repository ./transport-archive
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@content/docs/how-to/use-component-constructor.md` at line 356, The env-var
example command is missing the repository target; update the command string
"VERSION=1.2.3 IMAGE_VERSION=6.9.4 ocm add cv" to include the repository flag by
appending "--repository ./transport-archive" so the example is runnable in-place
(i.e., change the example invocation to "VERSION=1.2.3 IMAGE_VERSION=6.9.4 ocm
add cv --repository ./transport-archive").

86-86: ⚠️ Potential issue | 🟠 Major

Use canonical filesystem casing consistently.

Line 86 and Line 278 use fileSystem, while other sections use filesystem. Please standardize on filesystem to avoid copy/paste errors.

Proposed fix
-      type: fileSystem
+      type: filesystem

Also applies to: 278-278

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@content/docs/how-to/use-component-constructor.md` at line 86, Replace the
non-canonical casing "fileSystem" with the standard "filesystem" wherever it
appears in the document (specifically the YAML/config key usage shown as `type:
fileSystem` on line examples around the doc); search for the exact token
"fileSystem" and update to "filesystem" so all `type:` entries and examples are
consistent across the file (including the occurrences noted near the two
locations).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Duplicate comments:
In `@content/docs/how-to/use-component-constructor.md`:
- Line 356: The env-var example command is missing the repository target; update
the command string "VERSION=1.2.3 IMAGE_VERSION=6.9.4 ocm add cv" to include the
repository flag by appending "--repository ./transport-archive" so the example
is runnable in-place (i.e., change the example invocation to "VERSION=1.2.3
IMAGE_VERSION=6.9.4 ocm add cv --repository ./transport-archive").
- Line 86: Replace the non-canonical casing "fileSystem" with the standard
"filesystem" wherever it appears in the document (specifically the YAML/config
key usage shown as `type: fileSystem` on line examples around the doc); search
for the exact token "fileSystem" and update to "filesystem" so all `type:`
entries and examples are consistent across the file (including the occurrences
noted near the two locations).

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 09122885-18af-40b8-8106-716dd1005527

📥 Commits

Reviewing files that changed from the base of the PR and between 4df70b9 and 01344f6.

📒 Files selected for processing (4)
  • content/docs/how-to/inspect-component-descriptor.md
  • content/docs/how-to/model-products.md
  • content/docs/how-to/use-component-constructor.md
  • content/docs/tutorials/component-descriptor-example.md
💤 Files with no reviewable changes (1)
  • content/docs/tutorials/component-descriptor-example.md
🚧 Files skipped from review as they are similar to previous changes (2)
  • content/docs/how-to/model-products.md
  • content/docs/how-to/inspect-component-descriptor.md

Comment thread content/docs/how-to/use-component-constructor.md Outdated
@piotrjanik piotrjanik force-pushed the docs/889-component-authoring-documentation branch from 01344f6 to 9e42b3b Compare March 10, 2026 08:57

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@content/docs/how-to/model-products.md`:
- Around line 220-224: There are multiple consecutive blank lines just before
the closing step tag "{{< /step >}}"; edit the markdown block around that
closing tag and remove the extra empty lines so there is only a single blank
line immediately before "{{< /step >}}", ensuring the steps markup remains
correctly formatted.

In `@content/docs/reference/component-descriptor.md`:
- Around line 136-139: The markdown list of examples
(`github.com/open-component-model/ocm` and `acme.org/platform/frontend`) lacks a
blank line before it; insert a single blank line immediately above the list so
the Examples: paragraph and the subsequent bullet list are separated to satisfy
MD032 (i.e., ensure there is an empty line between the preceding paragraph and
the "- `github.com/open-component-model/ocm`" / "- `acme.org/platform/frontend`"
list).

In `@content/docs/tutorials/advanced-component-constructor.md`:
- Around line 419-423: There are multiple consecutive blank lines between the
closing </details> tag and the {{< /step >}} token in
content/docs/tutorials/advanced-component-constructor.md; open that section and
remove the extra empty lines so there is only a single blank line separating
</details> and {{< /step >}}.
- Around line 45-48: There's an extra blank line(s) between the paragraph "Each
box is an independent component version. Arrows represent `componentReferences`.
Leaf components carry the actual resources; parent components aggregate them."
and the "## Scenario" header; remove the extra blank line(s) so there is exactly
one blank line separating that paragraph and the "## Scenario" heading to
satisfy Markdown linting.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 70fa2f89-c731-47ad-9a89-651fef8f2550

📥 Commits

Reviewing files that changed from the base of the PR and between 01344f6 and 9e42b3b.

📒 Files selected for processing (8)
  • content/_index.md
  • content/docs/getting-started/deploy-helm-chart.md
  • content/docs/how-to/model-products.md
  • content/docs/reference/component-constructor.md
  • content/docs/reference/component-descriptor.md
  • content/docs/tutorials/advanced-component-constructor.md
  • content/docs/tutorials/complex-component-structure-deployment.md
  • content/docs/tutorials/component-descriptor-example.md
💤 Files with no reviewable changes (2)
  • content/docs/tutorials/complex-component-structure-deployment.md
  • content/docs/tutorials/component-descriptor-example.md
✅ Files skipped from review due to trivial changes (1)
  • content/docs/reference/component-constructor.md

Comment thread content/docs/how-to/model-products.md Outdated
Comment thread content/docs/reference/component-descriptor.md
Comment thread content/docs/tutorials/advanced-component-constructor.md Outdated
Comment thread content/docs/tutorials/advanced-component-constructor.md
Comment thread content/docs/how-to/model-products.md Outdated
Comment thread content/docs/how-to/model-products.md Outdated
Comment thread content/docs/how-to/model-products.md Outdated
Comment thread content/docs/how-to/model-products.md Outdated
Comment thread content/docs/how-to/model-products.md Outdated
Comment thread content/docs/how-to/model-products.md Outdated
Comment thread content/docs/how-to/model-products.md
Comment thread content/docs/reference/component-descriptor.md Outdated
Comment thread content/docs/reference/component-descriptor.md Outdated
Comment thread content/docs/reference/component-descriptor.md Outdated
Comment thread content/docs/reference/component-descriptor.md

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@content/docs/how-to/model-products.md`:
- Around line 25-32: The example topology shown in the mermaid diagram (nodes P,
B, F, C where P is "product v2.0.0" and C is "cache v2.0.0") is inconsistent
with the walkthrough steps and expected outputs because the `cache` component
(C) is never created; update the guide to keep the example consistent by either
removing the cache node from the diagram and any mentions of `cache` in the
constructor text, or adding explicit steps that create and register the `cache`
component (matching the `componentReferences` example) and updating the expected
outputs to include `cache v2.0.0` so the diagram, constructor, and walkthrough
all match.

In `@content/docs/reference/component-descriptor.md`:
- Around line 365-367: The "Full Example" section claims the example combines
"all sections above" but omits nestedDigests; either update the example under
the "Full Example" heading to include a representative nestedDigests entry
(matching the document's nestedDigests schema) or change the wording to
something like "most top-level sections above" and explicitly note that
nestedDigests is excluded; refer to the "Full Example" heading and the
nestedDigests field when making the change.

In `@content/docs/tutorials/advanced-component-constructor.md`:
- Around line 404-416: Update the "Expected output" for the `ocm get cv
acme-platform/transport-archive//github.com/acme.org/frontend:1.5.0 -o yaml`
verification to list the actual frontend resources (only `chart` and `image`)
and provider info (`acme.org`), removing `manifests` (which belongs to the
backend); locate the block that describes the expected component descriptor
output and change the bullet list from "- The `resources` section listing
`manifests`, `chart`, and `image`" to "- The `resources` section listing `chart`
and `image`" while keeping the provider note.
- Around line 187-188: The artifact entry using "type: filesystem" is invalid;
update the artifact type to the canonical name "directoryTree" (or the alias
"fileSystem") for the artifact with name "migrations" (and the other occurrence
noted around lines 494-495). Modify the YAML entries that currently read 'type:
filesystem' to 'type: directoryTree' (or 'type: fileSystem' if you prefer the
alias) so they match the component-descriptor artifact types.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: d58238b5-317c-4e74-8e36-e6e7ca695f58

📥 Commits

Reviewing files that changed from the base of the PR and between 9e42b3b and 345acc9.

📒 Files selected for processing (4)
  • content/docs/how-to/model-products.md
  • content/docs/reference/component-constructor.md
  • content/docs/reference/component-descriptor.md
  • content/docs/tutorials/advanced-component-constructor.md
🚧 Files skipped from review as they are similar to previous changes (1)
  • content/docs/reference/component-constructor.md

Comment thread content/docs/how-to/model-products.md Outdated
Comment thread content/docs/reference/component-descriptor.md Outdated
Comment thread content/docs/tutorials/advanced-component-constructor.md Outdated
Comment thread content/docs/tutorials/advanced-component-constructor.md Outdated
@piotrjanik piotrjanik force-pushed the docs/889-component-authoring-documentation branch 7 times, most recently from 464ce92 to e957352 Compare March 10, 2026 23:23
@piotrjanik piotrjanik force-pushed the docs/889-component-authoring-documentation branch from efdfe4b to 280fd98 Compare March 17, 2026 15:27
Comment thread content/docs/reference/component-constructor.md Outdated
@piotrjanik piotrjanik force-pushed the docs/889-component-authoring-documentation branch from 280fd98 to 7a0370e Compare March 18, 2026 14:28
@piotrjanik piotrjanik force-pushed the docs/889-component-authoring-documentation branch 2 times, most recently from 717697b to 722e30b Compare March 18, 2026 18:42
Comment thread content/docs/tutorials/advanced-component-constructor.md
Comment thread content/docs/tutorials/advanced-component-constructor.md
Comment thread content/docs/tutorials/advanced-component-constructor.md Outdated
Comment thread content/docs/tutorials/advanced-component-constructor.md
Comment thread content/docs/tutorials/advanced-component-constructor.md
Comment thread content/docs/reference/component-constructor.md Outdated
Comment thread content/docs/reference/component-constructor.md Outdated
Comment thread content/docs/reference/component-constructor.md Outdated
Comment thread content/docs/reference/component-constructor.md
Comment thread content/docs/how-to/model-products.md
@piotrjanik piotrjanik force-pushed the docs/889-component-authoring-documentation branch from 722e30b to 3889ef6 Compare March 19, 2026 11:49
@piotrjanik piotrjanik requested a review from fabianburth March 19, 2026 12:31
<!-- markdownlint-disable MD041 -->

Adds comprehensive documentation for component authoring with the new OCM CLI:

**New reference pages:**
- `reference/component-constructor.md` — field reference for `component-constructor.yaml`, the input format for `ocm add cv`
- `reference/component-descriptor.md` — field reference for the component descriptor output format (v2 schema)
- `reference/input-and-access-types.md` — field-level reference for all supported input types (`dir`, `file`, `helm/v1`, `utf8`) and access types (`OCIImage`, `localBlob`, `OCIImageLayer`, `Helm`)

**New how-to and tutorial:**
- `how-to/model-products.md` — step-by-step guide for modeling multi-component products with component references
- `tutorials/advanced-component-constructor.md` — tutorial covering multi-component constructors, labels, sources, and nesting patterns

**Replaced outdated content:**
- Removed `tutorials/complex-component-structure-deployment.md` (replaced by `model-products.md`)
- Removed `tutorials/component-descriptor-example.md` (replaced by `component-descriptor.md` reference)
- Moved and rewrote `tutorials/input-and-access-types.md` as a reference page, removing types not supported by the new OCM (`binary`, `docker`, `dockermulti`, `ociImage`, `spiff`, `gitHub`, `npm`, `s3`, `wget`)

<!--
Usage: `Fixes #<issue number>`, or `Fixes (paste link of issue)`.
-->

Fixes: open-component-model/ocm-project#889

Signed-off-by: Piotr Janik <piotr.janik@sap.com>
@piotrjanik piotrjanik force-pushed the docs/889-component-authoring-documentation branch from 3889ef6 to 6d29c7a Compare March 19, 2026 22:09
@piotrjanik piotrjanik enabled auto-merge (squash) March 20, 2026 09:26
…entation

Signed-off-by: Piotr Janik <piotr.janik@sap.com>
@piotrjanik piotrjanik force-pushed the docs/889-component-authoring-documentation branch from eb3ba14 to b7206e9 Compare March 20, 2026 09:27
@piotrjanik piotrjanik merged commit 73c50fd into open-component-model:main Mar 20, 2026
10 checks passed
@piotrjanik piotrjanik deleted the docs/889-component-authoring-documentation branch March 20, 2026 09:30
ocmbot Bot pushed a commit that referenced this pull request Mar 20, 2026
docs: add component authoring documentation

<!-- markdownlint-disable MD041 -->
#### What this PR does / why we need it

Adds comprehensive documentation for component authoring with the new
OCM CLI:

**New reference pages:**
- `reference/component-constructor.md` — field reference for
`component-constructor.yaml`, the input format for `ocm add cv`
- `reference/component-descriptor.md` — field reference for the
component descriptor output format (v2 schema)
- `reference/input-and-access-types.md` — field-level reference for all
supported input types (`dir`, `file`, `helm/v1`, `utf8`) and access
types (`OCIImage`, `localBlob`, `OCIImageLayer`, `Helm`)

**New how-to and tutorial:**
- `how-to/model-products.md` — step-by-step guide for modeling
multi-component products with component references
- `tutorials/advanced-component-constructor.md` — tutorial covering
multi-component constructors, labels, sources, and nesting patterns

**Replaced outdated content:**
- Removed `tutorials/complex-component-structure-deployment.md`
(replaced by `model-products.md`)
- Removed `tutorials/component-descriptor-example.md` (replaced by
`component-descriptor.md` reference)
- Moved and rewrote `tutorials/input-and-access-types.md` as a reference
page, removing types not supported by the new OCM (`binary`, `docker`,
`dockermulti`, `ociImage`, `spiff`, `gitHub`, `npm`, `s3`, `wget`)

#### Which issue(s) this PR fixes
<!--
Usage: `Fixes #<issue number>`, or `Fixes (paste link of issue)`.
-->

Fixes: open-component-model/ocm-project#889

---------

Signed-off-by: Piotr Janik <piotr.janik@sap.com> 73c50fd
@coderabbitai coderabbitai Bot mentioned this pull request Apr 1, 2026
7 tasks
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Component Authoring Documentation

5 participants