chore(docs): add onboarding and how we work guide by frewilhelm · Pull Request #2444 · open-component-model/open-component-model

frewilhelm · 2026-05-06T08:51:17Z

What this PR does / why we need it

Adds community documentation to the website as outlined in the onboarding epic. This PR introduces:

Developer Onboarding (/community/onboarding) - a guided entry point for new developers covering what OCM is, the mono-repo structure, technical layers, and learning paths.
How We Work (/community/how-we-work) - documents the team's work item hierarchy (initiatives, epics, tasks, spikes), project board, sprint intake process, meeting cadence, and decision-making.
Community section restructuring - replaces community.md (slug: /community/engagement) with a proper Hugo section _index.md, updates the nav menu to point to /community/, and adjusts page weights for logical ordering. The old /community/engagement/ URL is preserved via an alias redirect.
Existing page updates:
- community.md replaced by _index.md: adds Zulip channel, uses relref for the contributing link, improves description meta.
- contributing.md: removes "SAP" from AI policy, replaces duplicated channel info with a link to the community page, adds direct links to the mono-repo and website CONTRIBUTING.md files.
Cross-repo link updates - updates /community/engagement references in CONTRIBUTING.md, both cliff.toml changelog templates, SIG-Runtime-CHARTER.md, docs/community/README.md, the OCM v2 blog post, and the container image how-to guide.

Which issue(s) this PR fixes

Fixes open-component-model/ocm-project#991

Testing

How to test the changes

This is a documentation-only change. To verify locally:

cd website
npm run build

The Hugo build should complete without errors. To preview:

npm run dev

Then navigate to:

Verify that:

All internal links resolve (no 404s)
Mermaid diagrams render correctly on the onboarding and how-we-work pages
The community section landing page lists all child pages
Navigation menu "Community" link lands on the section page
/community/engagement/ redirects to /community/

netlify · 2026-05-06T08:51:22Z

✅ Deploy Preview for ocm-website ready!

Name	Link
🔨 Latest commit	`b15a156`
🔍 Latest deploy log	https://app.netlify.com/projects/ocm-website/deploys/6a01f5c7b77ec60008eb1dbd
😎 Deploy Preview	https://deploy-preview-2444--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-06T08:51:26Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 27cd3321-f2fb-4a68-bf32-df1a15516422

📥 Commits

Reviewing files that changed from the base of the PR and between 245fb06 and b15a156.

📒 Files selected for processing (2)

.github/config/wordlist.txt
website/content/community/onboarding.md

✅ Files skipped from review due to trivial changes (2)

.github/config/wordlist.txt
website/content/community/onboarding.md

📝 Walkthrough

Walkthrough

Restructures the website community area: updates community menu and changelog templates, expands the wordlist, adds a Community index, updates community pages (Zulip, contributing link), revises the contributing guide, and adds "How We Work" and onboarding pages.

Changes

Community Section Restructuring & Documentation Expansion

Layer / File(s)	Summary
Configuration, templates & wordlist `website/config/_default/menus/menus.en.toml`, `.github/config/wordlist.txt`, `cli/cliff.toml`, `kubernetes/controller/cliff.toml`, `CONTRIBUTING.md`	Community menu URL changed to `community/`; changelog templates updated to point to `/community/`; three words added to `.github/config/wordlist.txt` (`discoverable`, `hidechildren`, `standup`); root CONTRIBUTING link updated.
Community Index & Hub `website/content/community/_index.md`, `website/content/community/community.md`	New community index page added (front matter + hub content). Main community page description updated, Zulip section added, and Contributing link converted to internal relref/anchor.
Contributing Guide Updates `website/content/community/contributing.md`	Front-matter weight changed (2→3); "Before you push" links now reference both root and website CONTRIBUTING.md; community call anchor updated; AI-generated code contribution guidance replaced with four enumerated requirements; Getting Help consolidated to the Community Engagement page.
How We Work `website/content/community/how-we-work.md`	New page describing work hierarchy, project board views, issue intake/refinement flow, meetings, decision-making, and communication channels.
Developer Onboarding `website/content/community/onboarding.md`	New onboarding page added with prerequisites, OCM overview, mono-repo guidance, layered technical architecture (Mermaid diagrams), getting started, advanced topics, and contributing links.
Cross-site link updates & docs fixes `website/content/blog/ocm_v2_announcement.md`, `website/content/docs/how-to/container-image-usage.md`, `docs/community/README.md`, `docs/community/SIGs/Runtime/SIG-Runtime-CHARTER.md`, `website/content/governance/_index.md`	Propagate updated community link targets and adjust community-call links across blog, docs, governance, SIG charter, and container-image usage docs.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

open-component-model/open-component-model#2285: Also modifies contributing and community documentation across the site.
open-component-model/open-component-model#2231: Changes to the repository wordlist; overlaps with wordlist edits here.
open-component-model/open-component-model#2245: Related documentation edits to docs/community/README.md.

Suggested reviewers

piotrjanik
matthiasbruns

"🐰 I hopped through docs to clear the way,
A hub, onboarding, and guides today.
Menus relinked, three words I sowed,
Zulip and calls in the community mode.
Welcome, contributors — follow the road."

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main changes: adding onboarding and how-we-work documentation to the community section.
Description check	✅ Passed	The description is comprehensive and clearly related to the changeset, explaining all major modifications and providing testing instructions.
Linked Issues check	✅ Passed	The PR meets all primary objectives from issue `#991`: adds developer onboarding page with technical overview, creates how-we-work documentation, restructures community section, and updates links across repositories.
Out of Scope Changes check	✅ Passed	All changes are within scope: three new pages (onboarding, how-we-work, _index), updates to contributing guide, and cross-repo link updates to reflect new URL structure.
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

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

Generate code and open pull requests
Plan features and break down work
Investigate incidents and troubleshoot customer tickets together
Automate recurring tasks and respond to alerts with triggers
Summarize progress and report instantly

Built for teams:

Shared memory across your entire org—no repeating context
Per-thread sandboxes to safely plan and execute work
Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

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>

frewilhelm · 2026-05-06T09:24:01Z

@coderabbitai review

coderabbitai · 2026-05-06T09:24:07Z

✅ 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.

matthiasbruns

Content is great - I like the infos that are made. I think ocm still needs some kind of mentoring in the beginning due to the deep-tech nature (not part of this issue, but in general worth thinking about for people who are really interested and show that they would invest more)

…omponent-model into add-onboarding-guide

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

coderabbitai

♻️ Duplicate comments (1)

website/content/community/how-we-work.md (1)

11-12: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Resolve contradictory meeting-access statement.

Line 11-12 says all listed meetings are public, but Line 66 defines the retrospective as invite-only. Please narrow this statement so it matches the table and avoids confusing newcomers.

Suggested wording change

-This page describes how the OCM team organizes its day-to-day development work. All meetings listed here are open to
-the public - anyone is welcome to join, listen, or participate.
+This page describes how the OCM team organizes its day-to-day development work. Most meetings listed here are open to
+the public - anyone is welcome to join, listen, or participate unless explicitly marked otherwise.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@website/content/community/how-we-work.md` around lines 11 - 12, The opening
paragraph claims "All meetings listed here are open to the public" which
contradicts the table entry for the "Retrospective" that is invite-only; update
the opening sentence to be accurate and non-contradictory—for example change it
to "Most meetings listed here are open to the public; exceptions (such as the
Retrospective, which is invite-only) are noted below." Ensure you reference the
"Retrospective" by name in the sentence so newcomers see the exception and that
the table's invite-only status remains authoritative.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Duplicate comments:
In `@website/content/community/how-we-work.md`:
- Around line 11-12: The opening paragraph claims "All meetings listed here are
open to the public" which contradicts the table entry for the "Retrospective"
that is invite-only; update the opening sentence to be accurate and
non-contradictory—for example change it to "Most meetings listed here are open
to the public; exceptions (such as the Retrospective, which is invite-only) are
noted below." Ensure you reference the "Retrospective" by name in the sentence
so newcomers see the exception and that the table's invite-only status remains
authoritative.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: b6a21a94-6402-4114-9597-5090b8b7805e

📥 Commits

Reviewing files that changed from the base of the PR and between 17e6fd7 and cba3875.

📒 Files selected for processing (2)

website/content/community/how-we-work.md
website/content/community/onboarding.md

✅ Files skipped from review due to trivial changes (1)

website/content/community/onboarding.md

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

frewilhelm · 2026-05-08T09:49:11Z

@coderabbitai review

coderabbitai · 2026-05-08T09:49:19Z

✅ 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.

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

piotrjanik

LGTM, Really good job @frewilhelm

…omponent-model into add-onboarding-guide

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

…omponent-model into add-onboarding-guide

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

morri-son · 2026-05-11T14:46:42Z

https://deploy-preview-2444--ocm-website.netlify.app/ looks and reads cool. Great work!

jakobmoellerdev

well done!

#### What this PR does / why we need it Adds community documentation to the website as outlined in the onboarding epic. This PR introduces: - **Developer Onboarding** (`/community/onboarding`) - a guided entry point for new developers covering what OCM is, the mono-repo structure, technical layers, and learning paths. - **How We Work** (`/community/how-we-work`) - documents the team's work item hierarchy (initiatives, epics, tasks, spikes), project board, sprint intake process, meeting cadence, and decision-making. - **Community section restructuring** - replaces `community.md` (slug: `/community/engagement`) with a proper Hugo section `_index.md`, updates the nav menu to point to `/community/`, and adjusts page weights for logical ordering. The old `/community/engagement/` URL is preserved via an alias redirect. - **Existing page updates**: - `community.md` replaced by `_index.md`: adds Zulip channel, uses `relref` for the contributing link, improves description meta. - `contributing.md`: removes "SAP" from AI policy, replaces duplicated channel info with a link to the community page, adds direct links to the mono-repo and website `CONTRIBUTING.md` files. - **Cross-repo link updates** - updates `/community/engagement` references in `CONTRIBUTING.md`, both `cliff.toml` changelog templates, `SIG-Runtime-CHARTER.md`, `docs/community/README.md`, the OCM v2 blog post, and the container image how-to guide. #### Which issue(s) this PR fixes Fixes open-component-model/ocm-project#991 #### Testing ##### How to test the changes This is a documentation-only change. To verify locally: ```bash cd website npm run build ``` The Hugo build should complete without errors. To preview: ```bash npm run dev ``` Then navigate to: - http://localhost:1313/community/ - http://localhost:1313/community/onboarding/ - http://localhost:1313/community/how-we-work/ - http://localhost:1313/community/contributing/ Verify that: - All internal links resolve (no 404s) - Mermaid diagrams render correctly on the onboarding and how-we-work pages - The community section landing page lists all child pages - Navigation menu "Community" link lands on the section page - `/community/engagement/` redirects to `/community/` --------- Signed-off-by: Frederic Wilhelm <frederic.wilhelm@sap.com> Co-authored-by: Matthias Bruns <github@matthiasbruns.com> b32f4a0

…el#2444)  #### What this PR does / why we need it Adds community documentation to the website as outlined in the onboarding epic. This PR introduces: - **Developer Onboarding** (`/community/onboarding`) - a guided entry point for new developers covering what OCM is, the mono-repo structure, technical layers, and learning paths. - **How We Work** (`/community/how-we-work`) - documents the team's work item hierarchy (initiatives, epics, tasks, spikes), project board, sprint intake process, meeting cadence, and decision-making. - **Community section restructuring** - replaces `community.md` (slug: `/community/engagement`) with a proper Hugo section `_index.md`, updates the nav menu to point to `/community/`, and adjusts page weights for logical ordering. The old `/community/engagement/` URL is preserved via an alias redirect. - **Existing page updates**: - `community.md` replaced by `_index.md`: adds Zulip channel, uses `relref` for the contributing link, improves description meta. - `contributing.md`: removes "SAP" from AI policy, replaces duplicated channel info with a link to the community page, adds direct links to the mono-repo and website `CONTRIBUTING.md` files. - **Cross-repo link updates** - updates `/community/engagement` references in `CONTRIBUTING.md`, both `cliff.toml` changelog templates, `SIG-Runtime-CHARTER.md`, `docs/community/README.md`, the OCM v2 blog post, and the container image how-to guide. #### Which issue(s) this PR fixes Fixes open-component-model/ocm-project#991 #### Testing ##### How to test the changes This is a documentation-only change. To verify locally: ```bash cd website npm run build ``` The Hugo build should complete without errors. To preview: ```bash npm run dev ``` Then navigate to: - http://localhost:1313/community/ - http://localhost:1313/community/onboarding/ - http://localhost:1313/community/how-we-work/ - http://localhost:1313/community/contributing/ Verify that: - All internal links resolve (no 404s) - Mermaid diagrams render correctly on the onboarding and how-we-work pages - The community section landing page lists all child pages - Navigation menu "Community" link lands on the section page - `/community/engagement/` redirects to `/community/` --------- Signed-off-by: Frederic Wilhelm <frederic.wilhelm@sap.com> Co-authored-by: Matthias Bruns <github@matthiasbruns.com>

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

add onboarding and how we work guide

a0230ef

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

frewilhelm force-pushed the add-onboarding-guide branch from 52428df to a0230ef Compare May 6, 2026 08:51

frewilhelm added 4 commits May 6, 2026 10:57

fix linter issues

3c43455

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

fix minor inconsistencies

e8c97ee

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

condense work items

3b590c0

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

add words to wordlist

17e6fd7

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

github-actions Bot added the component/github-actions Changes on GitHub Actions or within `.github/` directory label May 6, 2026

Merge branch 'main' into add-onboarding-guide

b701ee3

frewilhelm marked this pull request as ready for review May 6, 2026 09:34

frewilhelm requested a review from a team as a code owner May 6, 2026 09:34

matthiasbruns reviewed May 6, 2026

View reviewed changes

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

matthiasbruns reviewed May 6, 2026

View reviewed changes

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

matthiasbruns reviewed May 6, 2026

View reviewed changes

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

matthiasbruns reviewed May 6, 2026

View reviewed changes

Comment thread website/content/community/how-we-work.md Outdated

matthiasbruns reviewed May 6, 2026

View reviewed changes

piotrjanik reviewed May 6, 2026

View reviewed changes

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

frewilhelm added 3 commits May 7, 2026 13:04

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

5648e65

…omponent-model into add-onboarding-guide

add comment to retro

5fa1802

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

clarify ODG

cba3875

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

frewilhelm requested review from jakobmoellerdev, matthiasbruns and piotrjanik May 7, 2026 11:25

coderabbitai Bot reviewed May 7, 2026

View reviewed changes

clarify openess of meetings

7668be7

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

Merge branch 'main' into add-onboarding-guide

73628a3

jakobmoellerdev reviewed May 8, 2026

View reviewed changes

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

soften wording

245fb06

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

frewilhelm requested a review from jakobmoellerdev May 8, 2026 15:18

jakobmoellerdev previously approved these changes May 11, 2026

View reviewed changes

jakobmoellerdev reviewed May 11, 2026

View reviewed changes

Comment thread website/content/community/onboarding.md

piotrjanik previously approved these changes May 11, 2026

View reviewed changes

frewilhelm added 2 commits May 11, 2026 14:49

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

ea12133

…omponent-model into add-onboarding-guide

reduce redundancy and use present sources (single source of truth)

4a06b94

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

frewilhelm dismissed stale reviews from piotrjanik and jakobmoellerdev via 4a06b94 May 11, 2026 12:58

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

552caa4

…omponent-model into add-onboarding-guide

frewilhelm requested review from jakobmoellerdev and piotrjanik May 11, 2026 12:59

fix linter issues

9d9372d

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

morri-son approved these changes May 11, 2026

View reviewed changes

jakobmoellerdev approved these changes May 11, 2026

View reviewed changes

Merge branch 'main' into add-onboarding-guide

b15a156

jakobmoellerdev enabled auto-merge (squash) May 11, 2026 15:29

jakobmoellerdev merged commit b32f4a0 into open-component-model:main May 11, 2026
36 checks passed

This was referenced May 12, 2026

chore(website): Adjust onboarding guide #2496

Merged

feat: how to interact with the SIG Runtime #2428

Merged

frewilhelm deleted the add-onboarding-guide branch May 12, 2026 12:56

coderabbitai Bot mentioned this pull request May 20, 2026

chore: add governance documentation from the community spec v1.0 #2172

Merged

1 task

coderabbitai Bot mentioned this pull request Jun 2, 2026

chore(docs): add community calendar #2724

Merged

Conversation

frewilhelm commented May 6, 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

Uh oh!

netlify Bot commented May 6, 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 6, 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 reviewers

Uh oh!

frewilhelm commented May 6, 2026

Uh oh!

coderabbitai Bot commented May 6, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

matthiasbruns left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

frewilhelm commented May 8, 2026

Uh oh!

coderabbitai Bot commented May 8, 2026

Uh oh!

Uh oh!

Uh oh!

piotrjanik left a comment

Choose a reason for hiding this comment

Uh oh!

morri-son commented May 11, 2026

Uh oh!

jakobmoellerdev left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

frewilhelm commented May 6, 2026 •

edited

Loading

netlify Bot commented May 6, 2026 •

edited

Loading

coderabbitai Bot commented May 6, 2026 •

edited

Loading