docs(contributor): rewrite, consolidate, and trim the contributor guide by mchmarny · Pull Request #1143 · NVIDIA/aicr

mchmarny · 2026-06-02T13:19:41Z

Summary

Restructure docs/contributor/ around contributor use cases instead of single-topic reference pages. Net: -4,887 lines across the contributor folder; 10 → 9 docs (one new + three consolidations + two deletions).

Consolidated: Merged validations.md into validator.md so all four validation surfaces (constraint, container-per-validator, bundle-time component validation, chainsaw health check) live in one disambiguated doc. Merged api-server-extending.md (entirely aspirational) into api-server.md. Renamed data.md → recipe.md and kwok-testing.md → tests.md to reflect content scope.
New: collector.md covers the previously undocumented snapshot-collector contributor surface.
Trimmed: cli.md 2,873 → 371 lines; api-server.md 1,145 → 292 lines; data.md 1,830 → 478 lines. Removed user-facing duplication (cURL examples, CI snippets, Grafana queries, K8s manifests), aspirational content (gRPC, GraphQL, LaunchDarkly), and stale code paths (6-layer middleware, 2-deployer list).
Landing page: index.md now leads with "is my change in scope?" and a use-case decision matrix; package list refreshed (was missing 17 packages).

Motivation/Context

The contributor guide had grown to 9,299 lines across 10 docs, much of it duplicating user docs, restating CLAUDE.md, or describing aspirational extensions that were never built. Contributors had no clear landing page, no map of which doc to read for "I want to add X", and the two validation docs (validator.md + validations.md) regularly produced wrong-doc PRs.

Per the audit findings:

17 packages were missing from index.md's package table
The middleware chain documented in api-server.md had wrong order and was missing 3 layers
Specificity() in data.md was missing the Platform clause (6 fields, not 5)
11 of 13 CLI subcommands were undocumented (diff, mirror, trust, all evidence subcommands, skill, bundle verify)
recipes/evidence/ runbook in maintaining.md references a directory that doesn't exist yet (future ADR-007 state)

Type of Change

Documentation only.

Components Affected

area/docs (contributor docs, doc sidebar, doc index)
Inbound link updates: CLAUDE.md / AGENTS.md / DEVELOPMENT.md / recipes/README.md / recipes/overlays/*-any.yaml source-code comments / docs/integrator/* / docs/user/cli-reference.md / docs/user/component-catalog.md / .github/copilot-instructions.md / demos/data.md

Implementation Notes

Preserved anchors (referenced from other docs):

recipe.md#mixin-composition (linked from integrator/recipe-development.md)
recipe.md#criteria-wildcard-overlays (linked from integrator/recipe-development.md and the 5 *-any.yaml overlay comments)
maintaining.md#exit-1-review-process and #evidenceexempt-bypass-policy (linked from integrator/recipe-development.md)

Renames were done with git mv so blame and history follow.

fern/versions/*-content/contributor/*.md copies were intentionally left alone — those are frozen at past release versions.

Boundary clarity is the single most enforced rewrite goal. Every doc now states what belongs in pkg/cli / pkg/server (user interaction, no business logic) vs pkg/client/v1 (facade) vs functional packages.

Testing

make lint — green (golangci-lint, yamllint, license headers, AGENTS.md sync, doc filenames, MDX safety, chart-version pins, BOM)
make test — green; 76.3% total coverage
Internal link audit across all 9 contributor docs — no broken refs
Cross-doc link audit — all renames propagated to inbound links

Risk Assessment

Low. Documentation-only change; no Go source modified. Inbound link rewrites are mechanical (sed with full path patterns); verified by grep + lint.

Checklist

make lint passes locally
make test passes locally
Inbound links updated across repo
Sidebar (docs/index.yml) updated
Doc index (docs/README.md) updated
Anchors used by other docs preserved
Commit signed

Restructure docs/contributor/ around use cases instead of single-topic reference pages. Net: -4,887 lines across the contributor folder; from 10 docs to 9 (one new + three consolidations). - index.md: rewrite as the landing page. Lead with "is my change in scope?" and a decision matrix mapping intent to the right doc. Update package list (was missing 17 packages). Add a "your first contribution" path. - data.md → recipe.md: rename. Doc now reads as "recipes, overlays, and mixins" — preserve #mixin-composition and #criteria-wildcard-overlays anchors. Add 3-way registry/overlay/ mixin decision matrix, BOM regen rule, deep-copy []any aliasing rule, MarshalYAMLDeterministic, correct 6-field Specificity(). - component.md: trim. Document all 5 deployers (was 2), nodeScheduling.system vs accelerated, valueOverrideKeys, ComponentConfig Deprecated marker. - collector.md (new): how to add a snapshot collector. Factory pattern, errgroup parallelism, context timeouts, read-only boundary, common pitfalls. - validator.md: merge validations.md in. Document all four validation surfaces (constraint, container-per-validator, bundle-time component validation, chainsaw health check) with a disambiguation table at the top. Add --no-cluster, PodLifecycle helper, phase ordering, fail-closed gates. - cli.md: trim from 2,873 → 371 lines. Drop user-facing duplication (CI examples, ops, troubleshooting). Add pkg/client/v1 facade boundary, cmd.Root().Writer pattern, flag-factory pattern, errors.ExitCodeFromError, list all 13 subcommands. - api-server.md: rewrite. Correct 8-layer middleware chain (was 6, wrong order). Add WriteErrorFromErr 4xx-vs-5xx rule, timeoutMiddleware, bodyLimitMiddleware, versionMiddleware, openapi_sync_test contract, and "adding an endpoint" walkthrough. - api-server-extending.md: delete. Was entirely aspirational (CORS, gRPC, GraphQL, LaunchDarkly, etc.). Concrete extension guidance lives in api-server.md. - validations.md: delete. Content merged into validator.md as one of the four validation surfaces. - kwok-testing.md → tests.md: rename and broaden. KWOK becomes one section among unit tests, chainsaw, integration, e2e, and make qualify. - maintaining.md: rewrite. Add actual release runbook (links to RELEASING.md), GITLAB_TOKEN gotcha, common breakages. Mark evidence-backed review as future state per ADR-007. Update inbound links across docs/, recipes/, CLAUDE.md, AGENTS.md, DEVELOPMENT.md, demos/, and copilot-instructions.md. Update docs/index.yml sidebar and docs/README.md doc index to match new file set and titles.

mchmarny · 2026-06-02T13:23:06Z

@pdmack PTAL that this doesn't break anything in Fern CI

coderabbitai · 2026-06-02T13:26:56Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: 216403a1-0dc2-4d12-8494-d4df38410795

📥 Commits

Reviewing files that changed from the base of the PR and between c933dec and 3ee2b6f.

📒 Files selected for processing (6)

docs/contributor/index.md
docs/contributor/maintaining.md
docs/contributor/recipe.md
docs/contributor/tests.md
docs/contributor/validator.md
recipes/README.md

📝 Walkthrough

Walkthrough

This PR reorganizes contributor documentation to clarify AICR's architecture and development guidance. It adds three new guides (recipe data models, comprehensive testing strategy, and collector patterns), rewrites five major contributor references (index, API server, components, validators, and maintaining), and updates all documentation links across the codebase to point to the reorganized structure. Old documentation files for data architecture, API server extensions, KWOK testing, and validations are removed, with their content consolidated or relocated to the new guides.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: restructuring and consolidating the contributor documentation guide.
Description check	✅ Passed	The description comprehensively explains the motivation, scope of changes, testing performed, and risk assessment of the documentation restructuring.
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.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch docs/contributor-rewrite

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

coderabbitai

Actionable comments posted: 7

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

Inline comments:
In `@docs/contributor/index.md`:
- Around line 146-164: The fenced code block containing the ASCII architecture
diagram should include a language tag to satisfy the MD040 lint rule; update the
fence that wraps the diagram (the triple-backtick block with the package
diagram) to use a language such as text (or convert to mermaid and use mermaid)
so the block starts with ```text (or ```mermaid) instead of just ```.
- Around line 285-286: Update the sentence that claims collectors
"self-register" to accurately describe the registration pattern: state that
collectors are wired explicitly via the Factory and snapshotter (not via an
init() self-registration), and revise the surrounding text to reference the
Factory and snapshotter registration flow and any required registration calls so
contributors are directed to the correct extension pattern.

In `@docs/contributor/maintaining.md`:
- Around line 47-49: The documentation uses the acronyms GHCR and OCI without
defining them; update the first occurrences of the tokens "GHCR" and "OCI" (the
lines containing those acronyms) to include their full forms on first use —
e.g., "GitHub Container Registry (GHCR)" and "Open Container Initiative (OCI)" —
and leave subsequent mentions as the acronym only to satisfy the docs/**/*.md
guideline.

In `@docs/contributor/recipe.md`:
- Around line 24-45: The markdown contains unlabeled fenced code blocks (notably
the ASCII diagram that includes "RecipeResult" and the surrounding box art)
which triggers MD040; update those fences to include an explicit language tag
(e.g., use ```text for diagrams and ```bash or ```text for shell/inline examples
as appropriate) so the diagram block and the other unlabeled fence mentioned in
the comment are labeled and pass markdownlint.

In `@docs/contributor/tests.md`:
- Around line 203-205: The fenced code block containing the path
"recipes/checks/<component>/health-check.yaml" in docs/contributor/tests.md is
missing a language tag (triggering MD040); update that fence to include a
language identifier (e.g., add "text" after the opening ```) so the block
becomes a labeled code fence and the markdown linter passes.

In `@docs/contributor/validator.md`:
- Around line 304-312: The fenced directory-tree code block in
docs/contributor/validator.md is missing a language tag (triggers MD040); update
the opening fence for the block that shows the validators/ tree (the block
listing context.go, runner.go, helper/pod.go, deployment/, performance/,
conformance/) to use a language label (use "text") so the fence becomes ```text
and markdownlint no longer reports MD040.

In `@recipes/README.md`:
- Line 11: Update the quick-reference table entry that currently reads "Create
new bundlers" to accurately reflect the linked guide by renaming that label to
"Create/modify components" (or similar) so it matches the target
../docs/contributor/component.md; locate the table row containing the string
"Create new bundlers" and replace only the label text while keeping the link
intact.

🪄 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: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: 87ea5958-1f21-456f-b51f-da3f5fc55932

📥 Commits

Reviewing files that changed from the base of the PR and between 5e89201 and c933dec.

📒 Files selected for processing (32)

.claude/CLAUDE.md
.github/copilot-instructions.md
AGENTS.md
DEVELOPMENT.md
demos/data.md
docs/README.md
docs/contributor/api-server-extending.md
docs/contributor/api-server.md
docs/contributor/cli.md
docs/contributor/collector.md
docs/contributor/component.md
docs/contributor/data.md
docs/contributor/index.md
docs/contributor/kwok-testing.md
docs/contributor/maintaining.md
docs/contributor/recipe.md
docs/contributor/tests.md
docs/contributor/validations.md
docs/contributor/validator.md
docs/index.yml
docs/integrator/data-extension.md
docs/integrator/data-flow.md
docs/integrator/recipe-development.md
docs/integrator/validator-extension.md
docs/user/cli-reference.md
docs/user/component-catalog.md
recipes/README.md
recipes/overlays/b200-any.yaml
recipes/overlays/gb200-any.yaml
recipes/overlays/h100-any.yaml
recipes/overlays/h200-any.yaml
recipes/overlays/rtx-pro-6000-any.yaml

💤 Files with no reviewable changes (4)

docs/contributor/validations.md
docs/contributor/api-server-extending.md
docs/contributor/kwok-testing.md
docs/contributor/data.md

github-actions · 2026-06-02T13:30:40Z

Coverage Report ✅

Metric	Value
Coverage	76.3%
Threshold	75%
Status	Pass

Coverage Badge

![Coverage](https://img.shields.io/badge/coverage-76.3%25-green)

No Go source files changed in this PR.

- Label 6 ASCII-diagram and path-only fenced code blocks with `text` language tag to satisfy MD040 (index.md, recipe.md, tests.md, validator.md). - Fix incorrect "self-register" claim about collectors in index.md. Collectors are constructed by pkg/collector.Factory and wired into the run by pkg/snapshotter — there is no init()-time registration. - Define GHCR and OCI on first mention in maintaining.md. - Rename recipes/README.md quick-reference label from "Create new bundlers" to "Add or modify components" so the link text matches the Components contributor guide it points to.

mchmarny · 2026-06-02T13:33:08Z

Addressed all 7 CodeRabbit review comments in 3ee2b6f:

MD040 fenced-code-language (5 fences across index.md, recipe.md, tests.md, validator.md): labeled each ASCII-diagram / path-only block as text.
self-register claim (index.md:286): corrected — collectors are constructed via pkg/collector.Factory and wired into the run by pkg/snapshotter. There is no init()-time registration. Pointed to collector.md.
GHCR / OCI acronyms (maintaining.md:48, 100): defined on first use as GitHub Container Registry (GHCR) and Open Container Initiative (OCI).
recipes/README.md:11: renamed label from "Create new bundlers" to "Add or modify components" to match the linked Components guide.

make lint green locally.

pdmack

Review — docs restructure

Overall this is a clean consolidation. Cross-references, sidebar nav, and CLAUDE.md/AGENTS.md sync all check out. One broken link and a few suggestions below.

Broken link

docs/contributor/maintaining.md:62 — recipe.md#bom-regeneration-rule should be recipe.md#bom-regeneration (the heading is ## BOM Regeneration, no -rule suffix)

Suggestions

Readiness phase ambiguity (docs/contributor/validator.md) — The doc says "Three phases" (deployment, performance, conformance), which is correct for container-per-validator checks. But readiness is a first-class field on ValidationConfig in pkg/recipe/validation.go and appears in recipe overlay examples. A one-liner noting that readiness uses inline constraint evaluation (not container checks) would prevent contributors from wondering where it went.
Missing package (docs/contributor/index.md) — pkg/recipe/oskind is absent from the package table. It's used by criteria and collectors. Worth adding if the table aims to be exhaustive.
Merge precedence arrow (docs/contributor/recipe.md ~line 297) — registry defaults → mixin → base chain → overlay leaf → CLI --set is correct (rightmost = highest priority), but on first read the arrow can look like temporal order. The narrative below clarifies it; a parenthetical like "(lowest → highest priority)" on the arrow line would help.

Nit

docs/contributor/api-server.md:52 — middleware.go#L45-L61 is a line-range GitHub link that will silently go stale when that file is edited. Not urgent, just fragile.

CI note (not caused by this PR)

fern check errors with ENOENT/500 on fern/versions/v0.14.0-content/README.md because frozen version content directories are only populated at publish time via git archive. This predates this PR — tracked separately.

mchmarny requested review from a team as code owners June 2, 2026 13:19

mchmarny added the documentation label Jun 2, 2026

mchmarny self-assigned this Jun 2, 2026

github-actions Bot added area/recipes area/ci area/docs size/XL labels Jun 2, 2026

mchmarny enabled auto-merge (squash) June 2, 2026 13:21

coderabbitai Bot reviewed Jun 2, 2026

View reviewed changes

lalitadithya approved these changes Jun 2, 2026

View reviewed changes

mchmarny merged commit 48cbb31 into main Jun 2, 2026
119 checks passed

mchmarny deleted the docs/contributor-rewrite branch June 2, 2026 13:47

pdmack reviewed Jun 2, 2026

View reviewed changes

mchmarny mentioned this pull request Jun 2, 2026

docs(contributor): address PR #1143 review feedback #1145

Merged

3 tasks

mchmarny added a commit that referenced this pull request Jun 2, 2026

docs(contributor): address PR #1143 review feedback (#1145)

3b0750e

This was referenced Jun 2, 2026

[Bug]: MDX safety check does not cover contributor docs #1147

Closed

[Bug]: MDX safety check does not cover contributor docs #1148

Closed

mchmarny mentioned this pull request Jun 2, 2026

fix(docs): cover contributor docs in MDX check; catch autolinks #1151

Merged

4 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(contributor): rewrite, consolidate, and trim the contributor guide#1143

docs(contributor): rewrite, consolidate, and trim the contributor guide#1143
mchmarny merged 2 commits into
mainfrom
docs/contributor-rewrite

mchmarny commented Jun 2, 2026

Uh oh!

mchmarny commented Jun 2, 2026

Uh oh!

coderabbitai Bot commented Jun 2, 2026 •

edited

Loading

Walkthrough

Estimated code review effort

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jun 2, 2026 •

edited

Loading

Uh oh!

mchmarny commented Jun 2, 2026

Uh oh!

Uh oh!

pdmack left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

mchmarny commented Jun 2, 2026

Summary

Motivation/Context

Type of Change

Components Affected

Implementation Notes

Testing

Risk Assessment

Checklist

Uh oh!

mchmarny commented Jun 2, 2026

Uh oh!

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

Uh oh!

Walkthrough

Estimated code review effort

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage Report ✅

Uh oh!

mchmarny commented Jun 2, 2026

Uh oh!

Uh oh!

pdmack left a comment

Choose a reason for hiding this comment

Review — docs restructure

Broken link

Suggestions

Nit

CI note (not caused by this PR)

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

coderabbitai Bot commented Jun 2, 2026 •

edited

Loading

github-actions Bot commented Jun 2, 2026 •

edited

Loading