chore(website): Adjust onboarding guide by frewilhelm · Pull Request #2496 · open-component-model/open-component-model

frewilhelm · 2026-05-12T08:27:39Z

What this PR does / why we need it

Enhances the developer onboarding page to surface per-layer documentation that was previously hard to discover. New contributors can now find READMEs, contributing guides, examples, and reference docs directly from the onboarding page without having to navigate the repository tree.

Additionally consolidates controller documentation by removing duplicated getting-started guides that now live on the website, and unifies the controller naming across the repository.

Changes:

Onboarding page restructured - The Technical Layers section now has a dedicated subsection for each layer (OCM Specification, Go Bindings, CLI, K8s Toolkit, ODG) with card grids linking to key documentation.
Section reordering - Moved "Getting Started" and "Advanced Topics" higher (after "What is OCM?") so contributors see the learning path before the code structure.
"Say Hello" callout - Added a callout in "Contributing and Engaging" encouraging newcomers to join the community call or daily standup.
How-we-work reflinks - Replaced hardcoded Slack/Zulip URLs with relative links to the community page sections (single source of truth).
Deleted outdated architecture doc - Removed kubernetes/controller/docs/architecture/technical-details.md which used stale terminology and was unreferenced.
Controller getting-started docs removed - Deleted kubernetes/controller/docs/getting-started/ (credentials, custom-rbac, deploy-helm-chart, deploy-helm-chart-bootstrap, setup) as these have been migrated to the website. The controller README now links to the website equivalents.
Controller name unified - Renamed "OCM K8s Toolkit" to "OCM Kubernetes Controller Toolkit" across all references (README, ADR, onboarding, conformance RBAC, examples, how-to).
Community call timing removed - Removed specific meeting times from onboarding to avoid staleness.

Which issue(s) this PR fixes

Related to open-component-model/ocm-project#991

Testing

How to test the changes

Documentation-only change. To verify locally:

cd website && npm run dev

All links were validated against the live site and the repository's main branch.

Verification

No code changes - documentation only
Hugo build passes without errors
All referenced URLs resolve correctly
Controller README links point to correct website pages

Signed-off-by: Frederic Wilhelm <frederic.wilhelm@sap.com>

…ng guides Signed-off-by: Frederic Wilhelm <frederic.wilhelm@sap.com>

netlify · 2026-05-12T08:27:45Z

✅ Deploy Preview for ocm-website ready!

Name	Link
🔨 Latest commit	`e5fc836`
🔍 Latest deploy log	https://app.netlify.com/projects/ocm-website/deploys/6a03188d567caf0008d46a5c
😎 Deploy Preview	https://deploy-preview-2496--ocm-website.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

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

coderabbitai · 2026-05-12T08:27:47Z

📝 Walkthrough

Walkthrough

This PR renames toolkit references to “OCM Kubernetes Controller Toolkit”, removes the "Resource Resolution and Verification" section from the Kubernetes controller architecture doc, and updates community onboarding/how-we-work pages to use internal anchor links and card-based navigation.

Changes

Kubernetes controller docs — technical-content removal

Layer / File(s)	Summary
Remove deprecated technical section `kubernetes/controller/docs/architecture/technical-details.md`	Deleted the "Resource Resolution and Verification" technical content (≈40 lines removed). No code or public API changes.

Kubernetes controller docs — naming and onboarding updates

Layer / File(s)	Summary
Toolkit renaming across docs and READMEs `README.md`, `kubernetes/controller/README.md`, `kubernetes/controller/examples/README.md`, `docs/adr/0015_sovereign_cloud_reference_scenario.md`	Replaced occurrences of “OCM K8s Toolkit” with “OCM Kubernetes Controller Toolkit” and adjusted nearby wording/line-wrapping and headings.
Getting-started and setup guidance `kubernetes/controller/docs/getting-started/*.md`	Updated multiple getting-started pages (`credentials.md`, `custom-rbac.md`, `deploy-helm-chart*.md`, `setup.md`) to use the new toolkit name, clarified credential notes (`.ocmconfig`, secret/configmap usage), and adjusted mermaid diagram labels.
Examples and README consistency `kubernetes/controller/examples/README.md`, `kubernetes/controller/README.md`	Aligned example descriptions and installation instructions with the new toolkit name; added a Getting Started bullet for configuring credentials.

Website — community navigation and onboarding restructure

Layer / File(s)	Summary
Meeting/escalation anchors `website/content/community/how-we-work.md`	Updated "Joining meetings" callout and TSC escalation steps to use internal community anchors (`/community/#zulip`, `/community/#slack`) instead of external channel URLs.
Onboarding card-grid and technical layers `website/content/community/onboarding.md`	Added "Getting Started" and "Advanced Topics" card-grid sections; restructured "Technical Layers" into subsections (Specification, Go Bindings, OCM CLI, OCM Kubernetes Controller Toolkit, Open Delivery Gear) with card navigation; added "Say Hello" tip linking to community touchpoints and renamed mermaid nodes to the new toolkit label.
How-to docs alignment `website/content/docs/how-to/custom-rbac.md`	Frontmatter and intro updated to consistently reference “OCM Kubernetes Controller Toolkit.”

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

open-component-model/open-component-model#1931: Modifies getting-started/setup.md related to the Kubernetes controller toolkit (Helm/OCI install path).
open-component-model/open-component-model#2444: Edits onboarding/how-we-work site pages similar to the onboarding/navigation changes here.
open-component-model/open-component-model#1996: Related README and toolkit installation documentation updates.

Suggested labels

area/documentation, component/ocm-website

Suggested reviewers

morri-son
piotrjanik

Poem

🐰 I hopped through docs to mend each line,

Renamed the toolkit, made links align.
Cards to guide, anchors to show,
Old tech notes cleared—onto the next row.
A tidy trail for folks who roam.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'chore(website): Adjust onboarding guide' broadly refers to onboarding changes, but the PR encompasses much more than onboarding—including naming changes across 12 files, deletion of an architecture doc, and reflink updates. The title is partially related to the main changes but understates the scope.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The pull request description clearly explains all major changes: onboarding restructuring, documentation consolidation, controller naming unification, and removal of outdated content.

_{✏️ 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.}

Signed-off-by: Frederic Wilhelm <frederic.wilhelm@sap.com>

piotrjanik

LGTM

morri-son · 2026-05-12T09:40:31Z

beside the question about k8s toolkit vs controllers, lgtm!

Signed-off-by: Frederic Wilhelm <frederic.wilhelm@sap.com>

…omponent-model into adjust-onboarding

Signed-off-by: Frederic Wilhelm <frederic.wilhelm@sap.com>

#### What this PR does / why we need it Enhances the developer onboarding page to surface per-layer documentation that was previously hard to discover. New contributors can now find READMEs, contributing guides, examples, and reference docs directly from the onboarding page without having to navigate the repository tree. Additionally consolidates controller documentation by removing duplicated getting-started guides that now live on the website, and unifies the controller naming across the repository. Changes: - **Onboarding page restructured** - The Technical Layers section now has a dedicated subsection for each layer (OCM Specification, Go Bindings, CLI, K8s Toolkit, ODG) with card grids linking to key documentation. - **Section reordering** - Moved "Getting Started" and "Advanced Topics" higher (after "What is OCM?") so contributors see the learning path before the code structure. - **"Say Hello" callout** - Added a callout in "Contributing and Engaging" encouraging newcomers to join the community call or daily standup. - **How-we-work reflinks** - Replaced hardcoded Slack/Zulip URLs with relative links to the community page sections (single source of truth). - **Deleted outdated architecture doc** - Removed `kubernetes/controller/docs/architecture/technical-details.md` which used stale terminology and was unreferenced. - **Controller getting-started docs removed** - Deleted `kubernetes/controller/docs/getting-started/` (credentials, custom-rbac, deploy-helm-chart, deploy-helm-chart-bootstrap, setup) as these have been migrated to the website. The controller README now links to the website equivalents. - **Controller name unified** - Renamed "OCM K8s Toolkit" to "OCM Kubernetes Controller Toolkit" across all references (README, ADR, onboarding, conformance RBAC, examples, how-to). - **Community call timing removed** - Removed specific meeting times from onboarding to avoid staleness. #### Which issue(s) this PR fixes Related to open-component-model/ocm-project#991 #### Testing ##### How to test the changes Documentation-only change. To verify locally: ```bash cd website && npm run dev ``` All links were validated against the live site and the repository's main branch. ##### Verification - [x] No code changes - documentation only - [x] Hugo build passes without errors - [x] All referenced URLs resolve correctly - [x] Controller README links point to correct website pages --------- Signed-off-by: Frederic Wilhelm <frederic.wilhelm@sap.com> 7f656dc

frewilhelm added 3 commits May 12, 2026 10:24

remove outdated architecture document

886a3b1

Signed-off-by: Frederic Wilhelm <frederic.wilhelm@sap.com>

use reflink to section

40f53bb

Signed-off-by: Frederic Wilhelm <frederic.wilhelm@sap.com>

adjust onboarding document with references to examples and contributi…

a0eb41d

…ng guides Signed-off-by: Frederic Wilhelm <frederic.wilhelm@sap.com>

github-actions Bot added kind/chore chore, maintenance, etc. size/m Medium labels May 12, 2026

remove time of community call in onboarding

5624d8e

Signed-off-by: Frederic Wilhelm <frederic.wilhelm@sap.com>

frewilhelm marked this pull request as ready for review May 12, 2026 08:35

frewilhelm requested a review from a team as a code owner May 12, 2026 08:35

piotrjanik previously approved these changes May 12, 2026

View reviewed changes

morri-son reviewed May 12, 2026

View reviewed changes

Comment thread website/content/community/onboarding.md Outdated

Skarlso previously approved these changes May 12, 2026

View reviewed changes

frewilhelm added 2 commits May 12, 2026 13:50

unify controller name

398b32c

Signed-off-by: Frederic Wilhelm <frederic.wilhelm@sap.com>

Merge branch 'main' of https://github.com/open-component-model/open-c…

b57b05a

…omponent-model into adjust-onboarding

frewilhelm dismissed stale reviews from Skarlso and piotrjanik via b57b05a May 12, 2026 11:58

github-actions Bot added the area/documentation Documentation related label May 12, 2026

jakobmoellerdev previously approved these changes May 12, 2026

View reviewed changes

replace getting started docs with website docs

e5fc836

Signed-off-by: Frederic Wilhelm <frederic.wilhelm@sap.com>

frewilhelm dismissed jakobmoellerdev’s stale review via e5fc836 May 12, 2026 12:09

github-actions Bot added size/l Large and removed size/m Medium labels May 12, 2026

frewilhelm requested review from Skarlso, jakobmoellerdev, morri-son and piotrjanik May 12, 2026 12:44

morri-son approved these changes May 12, 2026

View reviewed changes

jakobmoellerdev approved these changes May 12, 2026

View reviewed changes

jakobmoellerdev merged commit 7f656dc into open-component-model:main May 12, 2026
37 checks passed

frewilhelm deleted the adjust-onboarding branch May 12, 2026 12:55

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore(website): Adjust onboarding guide#2496

chore(website): Adjust onboarding guide#2496
jakobmoellerdev merged 7 commits into
open-component-model:mainfrom
frewilhelm:adjust-onboarding

frewilhelm commented May 12, 2026 •

edited

Loading

Uh oh!

netlify Bot commented May 12, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented May 12, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Suggested reviewers

Poem

Uh oh!

piotrjanik left a comment

Uh oh!

Uh oh!

morri-son commented May 12, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

frewilhelm commented May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this PR does / why we need it

Which issue(s) this PR fixes

Testing

How to test the changes

Verification

Uh oh!

netlify Bot commented May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for ocm-website ready!

Uh oh!

coderabbitai Bot commented May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Suggested reviewers

Poem

Uh oh!

piotrjanik left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

morri-son commented May 12, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

frewilhelm commented May 12, 2026 •

edited

Loading

netlify Bot commented May 12, 2026 •

edited

Loading

coderabbitai Bot commented May 12, 2026 •

edited

Loading