docs: add component authoring how-to guides#739
Conversation
✅ Deploy Preview for open-component-model ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Note Reviews pausedIt 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 Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds 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
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
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
📝 Coding Plan
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. Comment |
88bf72c to
4df70b9
Compare
There was a problem hiding this comment.
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
📒 Files selected for processing (4)
content/docs/how-to/inspect-component-descriptor.mdcontent/docs/how-to/model-products.mdcontent/docs/how-to/use-component-constructor.mdcontent/docs/tutorials/component-descriptor-example.md
💤 Files with no reviewable changes (1)
- content/docs/tutorials/component-descriptor-example.md
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (2)
content/docs/how-to/use-component-constructor.md (2)
356-356:⚠️ Potential issue | 🟡 MinorMake the env-var command runnable in-place.
Line 356 omits the repository target used elsewhere in this guide. Add
--repository ./transport-archiveso 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 | 🟠 MajorUse a single canonical artifact type name (
filesystem) in examples.Line 86 and Line 278 use
type: fileSystem, while Line 186 and Line 304 usetype: filesystem. Please standardize onfilesystemto 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.mdAlso 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
📒 Files selected for processing (5)
content/docs/getting-started/create-component-version.mdcontent/docs/how-to/inspect-component-descriptor.mdcontent/docs/how-to/model-products.mdcontent/docs/how-to/use-component-constructor.mdcontent/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
4df70b9 to
01344f6
Compare
There was a problem hiding this comment.
♻️ Duplicate comments (2)
content/docs/how-to/use-component-constructor.md (2)
356-356:⚠️ Potential issue | 🟡 MinorMake the env-var command runnable in-place.
Line 356 omits the repository target used earlier in the guide. Add
--repository ./transport-archiveso 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 | 🟠 MajorUse canonical
filesystemcasing consistently.Line 86 and Line 278 use
fileSystem, while other sections usefilesystem. Please standardize onfilesystemto avoid copy/paste errors.Proposed fix
- type: fileSystem + type: filesystemAlso 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
📒 Files selected for processing (4)
content/docs/how-to/inspect-component-descriptor.mdcontent/docs/how-to/model-products.mdcontent/docs/how-to/use-component-constructor.mdcontent/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
01344f6 to
9e42b3b
Compare
There was a problem hiding this comment.
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
📒 Files selected for processing (8)
content/_index.mdcontent/docs/getting-started/deploy-helm-chart.mdcontent/docs/how-to/model-products.mdcontent/docs/reference/component-constructor.mdcontent/docs/reference/component-descriptor.mdcontent/docs/tutorials/advanced-component-constructor.mdcontent/docs/tutorials/complex-component-structure-deployment.mdcontent/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
There was a problem hiding this comment.
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
📒 Files selected for processing (4)
content/docs/how-to/model-products.mdcontent/docs/reference/component-constructor.mdcontent/docs/reference/component-descriptor.mdcontent/docs/tutorials/advanced-component-constructor.md
🚧 Files skipped from review as they are similar to previous changes (1)
- content/docs/reference/component-constructor.md
464ce92 to
e957352
Compare
efdfe4b to
280fd98
Compare
280fd98 to
7a0370e
Compare
717697b to
722e30b
Compare
722e30b to
3889ef6
Compare
<!-- 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>
3889ef6 to
6d29c7a
Compare
…entation Signed-off-by: Piotr Janik <piotr.janik@sap.com>
eb3ba14 to
b7206e9
Compare
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
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 forcomponent-constructor.yaml, the input format forocm add cvreference/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 referencestutorials/advanced-component-constructor.md— tutorial covering multi-component constructors, labels, sources, and nesting patternsReplaced outdated content:
tutorials/complex-component-structure-deployment.md(replaced bymodel-products.md)tutorials/component-descriptor-example.md(replaced bycomponent-descriptor.mdreference)tutorials/input-and-access-types.mdas 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