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

chore: Align docs to templates, style and wording before release#787

Merged
morri-son merged 20 commits into
open-component-model:mainfrom
morri-son:align-docs-to-templates-and-wording
Mar 26, 2026
Merged

chore: Align docs to templates, style and wording before release#787
morri-son merged 20 commits into
open-component-model:mainfrom
morri-son:align-docs-to-templates-and-wording

Conversation

@morri-son

Copy link
Copy Markdown
Contributor

What this PR does / why we need it

Align all docs to same look-and-feel and templates

  • Use steps callouts in how-tos, gettings started and tutorials
  • Name Flux consistently
  • Use "What you'll learn" as "## Header" in all docs
  • Add Next Steps to all docs and sort items to "next steps" and "related documentation"

On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com>
Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com>
Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
…eps to all docs.

On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com>
Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com>
Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com>
Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com>
Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
@morri-son morri-son requested a review from a team as a code owner March 25, 2026 19:58
@morri-son morri-son added the kind/chore chore, maintenance, etc. label Mar 25, 2026
@netlify

netlify Bot commented Mar 25, 2026

Copy link
Copy Markdown

Deploy Preview for open-component-model ready!

Name Link
🔨 Latest commit 29cb62c
🔍 Latest deploy log https://app.netlify.com/projects/open-component-model/deploys/69c555e1e48f78000899faa6
😎 Deploy Preview https://deploy-preview-787--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.

@morri-son morri-son changed the title chore: Align docs to templates and wording chore: Align docs to templates, style and wording Mar 25, 2026
@coderabbitai

coderabbitai Bot commented Mar 25, 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

Documentation-only edits across many pages: terminology changed from “FluxCD” to “Flux,” relref/link syntax and section headings standardized, tutorials updated with “What You’ll Learn,” working-directory create/cd and rm -rf cleanup steps, and Next Steps / Related Documentation lists reorganized.

Changes

Cohort / File(s) Summary
Terminology: Flux → Flux
content/docs/concepts/ocm-controllers.md, content/docs/tutorials/deploy-helm-chart-bootstrap.md
Replaced “FluxCD” wording with “Flux” across prose and diagram labels; updated deployer link targets.
Tutorial structure, setup & cleanup
content/docs/tutorials/advanced-component-constructor.md, content/docs/tutorials/configure-resolvers.md, content/docs/tutorials/configure-credentials-for-controllers.md, content/docs/tutorials/signing-and-verification.md, content/docs/tutorials/configure-resolvers.md
Added/standardized “What You’ll Learn” and estimated times, replaced callouts with headers, added dedicated working-directory create/cd steps and rm -rf cleanup commands, and minor wording/formatting edits.
Getting‑started edits
content/docs/getting-started/deploy-helm-chart.md, content/docs/getting-started/setup-controller-environment.md
Clarified rgd.yaml baseUrl replacement, refined instance file wording, added rm -rf /tmp/helm-deploy cleanup, and rephrased cluster teardown to make kind delete cluster an explicit/optional command.
How‑to / Next Steps / Related Documentation reorg
content/docs/how-to/transfer-helm-charts.md, content/docs/how-to/air-gap-transfer.md, content/docs/how-to/container-image-usage.md, content/docs/how-to/custom-rbac.md, content/docs/how-to/generate-signing-keys.md, content/docs/how-to/legacy-credential-compatibility.md, content/docs/how-to/migrate-from-deprecated-resolvers.md, content/docs/how-to/model-products.md, content/docs/how-to/resolve-components-from-multiple-repositories.md
Reorganized bottom-page navigation: added/renamed “Next Steps” and “Related Documentation” sections, adjusted relref labels and link targets, added “You’ll end up with” and estimated time in transfer how‑to, and restructured major how-to content formatting (steps/callouts).
Concepts / links & small edits
content/docs/concepts/transfer-concept.md, content/docs/concepts/component-identity.md, content/docs/concepts/resolvers.md, content/docs/overview/how-ocm-works.md, content/docs/overview/core-model.md
Removed one localization link, reorganized Next Steps vs Related Documentation lists and relabels, and replaced a custom relref wrapper with Hugo {{< relref "..." >}} syntax.
Large formatting restructure
content/docs/how-to/container-image-usage.md
Converted callouts to step blocks and headings, adjusted YAML snippet formatting and displayed outputs; substantial Markdown/templating reformatting.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

Suggested labels

area/documentation

Suggested reviewers

  • jakobmoellerdev
  • frewilhelm

Poem

🐰 I hopped through pages, tidy and quick,
Flux now bounds where FluxCD used to stick,
Temp dirs swept clean with a soft little sweep,
Links and headings set in neat little heaps,
A joyful thump — the docs sleep sweet.

🚥 Pre-merge checks | ✅ 3
✅ Passed checks (3 passed)
Check name Status Explanation
Title check ✅ Passed The title accurately summarizes the main objective of the changeset: aligning documentation to templates, style, and wording conventions before a release.
Description check ✅ Passed The description clearly outlines the PR's purpose and specific documentation improvements: template standardization, Flux naming consistency, header formatting, and Next Steps organization.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

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.

@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/getting-started/setup-controller-environment.md`:
- Around line 295-296: Rewrite the two sentences "To remove the local kind
cluster after testing you can execute the following command." and "You can just
keep it when you want to use the same cluster for the next steps in the
tutorial." to a single clearer pair of lines that read smoothly and match the
guide's tone — e.g. first tell the reader how to delete the local kind cluster
after testing, then state that keeping the cluster is fine if they plan to reuse
it for subsequent tutorial steps; ensure concise phrasing and consistent voice
with surrounding instructions.

In `@content/docs/tutorials/advanced-component-constructor.md`:
- Line 627: Replace the non-idempotent cleanup command "rm -r
/tmp/ocm-multi-component" with the force-and-recursive variant "rm -rf
/tmp/ocm-multi-component" so the tutorial step no longer errors when the
directory is already absent.

In `@content/docs/tutorials/configure-resolvers.md`:
- Line 332: Replace the non-idempotent cleanup command "rm -r
/tmp/ocm-resolver-tutorial" with a recursive + force removal to make re-runs
safe; locate the occurrence of that exact command in the configure-resolvers
tutorial content and change it to "rm -rf /tmp/ocm-resolver-tutorial" so
repeated cleanup won't fail when the directory is already gone.

In `@content/docs/tutorials/deploy-helm-chart-bootstrap.md`:
- Line 101: The Mermaid diagram's class assignment references the old subgraph
identifier fluxCD but the subgraph was renamed to flux, so update the class
definition/reference to use the new identifier "flux" (e.g., change any
occurrence of classDef/class or class assignments targeting fluxCD to target
flux) ensuring the class styling lines that reference fluxCD now match the
subgraph name flux so the styles apply correctly to subgraph flux.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 81a12a6b-d05c-4db7-ab16-c30190f8f704

📥 Commits

Reviewing files that changed from the base of the PR and between 0092743 and cd7cc85.

📒 Files selected for processing (11)
  • content/docs/concepts/ocm-controllers.md
  • content/docs/concepts/transfer-concept.md
  • content/docs/getting-started/deploy-helm-chart.md
  • content/docs/getting-started/setup-controller-environment.md
  • content/docs/how-to/air-gap-transfer.md
  • content/docs/how-to/transfer-helm-charts.md
  • content/docs/overview/how-ocm-works.md
  • content/docs/tutorials/advanced-component-constructor.md
  • content/docs/tutorials/configure-resolvers.md
  • content/docs/tutorials/deploy-helm-chart-bootstrap.md
  • content/docs/tutorials/signing-and-verification.md

Comment thread content/docs/getting-started/setup-controller-environment.md Outdated
Comment thread content/docs/tutorials/advanced-component-constructor.md Outdated
Comment thread content/docs/tutorials/configure-resolvers.md Outdated
Comment thread content/docs/tutorials/deploy-helm-chart-bootstrap.md
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com>
Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com>
Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
@morri-son

Copy link
Copy Markdown
Contributor Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Mar 26, 2026

Copy link
Copy Markdown
✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@morri-son morri-son enabled auto-merge (squash) March 26, 2026 10:44
@morri-son morri-son changed the title chore: Align docs to templates, style and wording chore: Align docs to templates, style and wording before release Mar 26, 2026
Comment thread content/docs/concepts/transfer-concept.md Outdated
Comment thread content/docs/getting-started/deploy-helm-chart.md
Comment thread content/docs/how-to/air-gap-transfer.md Outdated
Comment thread content/docs/tutorials/advanced-component-constructor.md
Comment thread content/docs/tutorials/advanced-component-constructor.md
Comment thread content/docs/tutorials/configure-resolvers.md
Comment thread content/docs/tutorials/configure-resolvers.md
Comment thread content/docs/tutorials/signing-and-verification.md

@frewilhelm frewilhelm left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Please make sure that it renders correctly :D

Comment thread content/docs/tutorials/deploy-helm-chart-bootstrap.md Outdated
morri-son and others added 7 commits March 26, 2026 14:10
Co-authored-by: Frederic Wilhelm <fre.wilhelm@gmail.com>
Signed-off-by: Gerald Morrison <67469729+morri-son@users.noreply.github.com>
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com>
Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com>
Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com>
Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com>
Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
…ates-and-wording

On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com>
Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com>
Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
@morri-son

Copy link
Copy Markdown
Contributor Author

@coderabbitai review

On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com>
Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
@coderabbitai

coderabbitai Bot commented Mar 26, 2026

Copy link
Copy Markdown
✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@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: 5

🤖 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/container-image-usage.md`:
- Line 34: The step heading "Create a simple component constructor" inside the
{{< step >}} block is using an H2 (##) but must be an H3 (###); update this and
the other occurrences mentioned (lines with the same pattern at the other step
blocks) so all step titles within {{< step >}} use level-3 headings (e.g.,
change "## Create a simple component constructor" to "### Create a simple
component constructor") to match the template's visual hierarchy.
- Around line 84-85: Replace the blockquote-style notes that start with the
emoji heading "📣📣 **Note**" (the instances containing the sentence about
updating the `identity` fields if you don't use `ghcr.io`) with the project’s
standard Hugo callout shortcode; locate the two occurrences (the one beginning
with "📣📣 **Note**" and the later repeated note) and swap each blockquote
wrapper for the callout shortcode wrapper while keeping the inner text identical
and preserving code formatting/inline backticks.

In `@content/docs/how-to/migrate-from-deprecated-resolvers.md`:
- Line 262: The document contains a second top-level heading "Related
Documentation" using a single "#" which triggers MD025; change that heading to
an H2 by replacing "# Related Documentation" with "## Related Documentation" so
the file keeps a single H1 title and satisfies markdownlint.

In `@content/docs/how-to/resolve-components-from-multiple-repositories.md`:
- Line 139: Change the markdown header string "## Related documentation" to
title case "## Related Documentation" to match the repository's standardized
section naming; locate the header exactly as "## Related documentation" in the
document and update it to "## Related Documentation".
- Around line 136-137: Update the duplicated link label "Tutorial: Working with
Resolvers Tutorial" so it uses a single, consistent form (e.g., "Tutorial:
Working with Resolvers" or "Working with Resolvers") while keeping the same
relref target ({{< relref "docs/tutorials/configure-resolvers.md" >}}); replace
the existing label text to remove the extra "Tutorial".
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 617aa74d-c78e-414b-9554-c7d556ddccae

📥 Commits

Reviewing files that changed from the base of the PR and between 4a79c8a and 635fa35.

📒 Files selected for processing (15)
  • content/docs/concepts/component-identity.md
  • content/docs/concepts/resolvers.md
  • content/docs/concepts/transfer-concept.md
  • content/docs/how-to/air-gap-transfer.md
  • content/docs/how-to/container-image-usage.md
  • content/docs/how-to/custom-rbac.md
  • content/docs/how-to/generate-signing-keys.md
  • content/docs/how-to/legacy-credential-compatibility.md
  • content/docs/how-to/migrate-from-deprecated-resolvers.md
  • content/docs/how-to/model-products.md
  • content/docs/how-to/resolve-components-from-multiple-repositories.md
  • content/docs/how-to/transfer-helm-charts.md
  • content/docs/overview/core-model.md
  • content/docs/tutorials/advanced-component-constructor.md
  • content/docs/tutorials/configure-credentials-for-controllers.md
✅ Files skipped from review due to trivial changes (9)
  • content/docs/how-to/generate-signing-keys.md
  • content/docs/how-to/custom-rbac.md
  • content/docs/overview/core-model.md
  • content/docs/how-to/legacy-credential-compatibility.md
  • content/docs/tutorials/configure-credentials-for-controllers.md
  • content/docs/how-to/transfer-helm-charts.md
  • content/docs/how-to/model-products.md
  • content/docs/concepts/component-identity.md
  • content/docs/concepts/transfer-concept.md
🚧 Files skipped from review as they are similar to previous changes (1)
  • content/docs/tutorials/advanced-component-constructor.md

Comment thread content/docs/how-to/container-image-usage.md Outdated
Comment thread content/docs/how-to/container-image-usage.md
Comment thread content/docs/how-to/migrate-from-deprecated-resolvers.md Outdated
Comment thread content/docs/how-to/resolve-components-from-multiple-repositories.md Outdated
Comment thread content/docs/how-to/resolve-components-from-multiple-repositories.md Outdated
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com>
Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com>
Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
@morri-son morri-son requested a review from frewilhelm March 26, 2026 14:56
@morri-son

Copy link
Copy Markdown
Contributor Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Mar 26, 2026

Copy link
Copy Markdown
✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com>
Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com>
Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
@morri-son morri-son merged commit be71642 into open-component-model:main Mar 26, 2026
10 checks passed
ocmbot Bot pushed a commit that referenced this pull request Mar 26, 2026
<!-- markdownlint-disable MD041 -->
#### What this PR does / why we need it
Align all docs to same look-and-feel and templates

- Use steps callouts in how-tos, gettings started and tutorials
- Name Flux consistently
- Use "What you'll learn" as "## Header" in all docs
- Add Next Steps to all docs and sort items to "next steps" and "related
documentation"

---------

Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
Co-authored-by: Gerald Morrison (SAP) <gerald.morrison@sap.com> be71642
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

kind/chore chore, maintenance, etc.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants