Skip to content

Update the CLI docs path#99

Open
adamwg wants to merge 3 commits into
crossplane:mainfrom
adamwg:awg/update-docs-paths
Open

Update the CLI docs path#99
adamwg wants to merge 3 commits into
crossplane:mainfrom
adamwg:awg/update-docs-paths

Conversation

@adamwg

@adamwg adamwg commented Jun 10, 2026

Copy link
Copy Markdown
Member

Description of your changes

The CLI docs are now versioned separately from the rest of the docs, in preparation for the CLI version diverging from core. Update it in our contributing docs and the CI jobs where we validate generated docs changes. Also update the docs template to match the current documentation page.

While we're here, make the dynamically generated help for crossplane xpkg init stable across runs by sorting the template names. This will reduce unnecessary churn when we automate docs updates.

I have:

The CLI docs are now versioned separately from the rest of the docs, in
preparation for the CLI version diverging from core. Update it in our
contributing docs and the CI jobs where we validate generated docs changes.

Signed-off-by: Adam Wolfe Gordon <awg@upbound.io>
@adamwg adamwg requested review from a team, jcogilvie and tampakrap as code owners June 10, 2026 16:16
@adamwg adamwg requested review from jbw976 and removed request for a team June 10, 2026 16:16
adamwg added 2 commits June 11, 2026 15:23
Signed-off-by: Adam Wolfe Gordon <awg@upbound.io>
Ensure stable help output (and generated documentation) by sorting the template
names in the dynamically-generated part of the `crossplane xpkg init` help.

Signed-off-by: Adam Wolfe Gordon <awg@upbound.io>
@coderabbitai

coderabbitai Bot commented Jun 11, 2026

Copy link
Copy Markdown

Review Change Stack

📝 Walkthrough

Walkthrough

This PR updates documentation paths and ensures deterministic help output. The docs generation path shifts from content/master/cli/ to content/cli/master/ in CI workflows and contributor documentation. The init command's help text is made deterministic by sorting template names before rendering them.

Changes

Documentation and help output improvements

Layer / File(s) Summary
Documentation path restructuring
.github/workflows/ci.yml, CONTRIBUTING.md
CI validate-docs job and contributing guide example updated to generate and reference command reference from docs/content/cli/master/command-reference.md instead of docs/content/master/cli/command-reference.md.
Deterministic help output for templates
cmd/crossplane/xpkg/init.go
Init command imports maps and slices utilities; initCmd.Help() now sorts template names and iterates over them in stable order instead of direct map iteration.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Suggested reviewers

  • tampakrap
  • jcogilvie
🚥 Pre-merge checks | ✅ 6
✅ Passed checks (6 passed)
Check name Status Explanation
Title check ✅ Passed The title accurately describes the main change: updating CLI documentation paths across contributing docs and CI workflows.
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.
Breaking Changes ✅ Passed Only cmd/crossplane/xpkg/init.go changed: initCmd flags/args (Directory, RunInitScript, RefName, etc.) are intact; change is just deterministic Help() sorting via maps/slices.
Feature Gate Requirement ✅ Passed PR #99 only updates CI/docs paths and sorts xpkg init help; no changes under apis/** or additions of experimental API/behavior without feature gating.
Description check ✅ Passed The pull request description clearly outlines the changes: updating CLI docs paths in contributing docs and CI jobs, updating the docs template, and sorting template names for stable help output. It directly aligns with the changeset across all modified files.

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


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.

🧹 Nitpick comments (1)
.github/workflows/ci.yml (1)

205-205: Keep the CLI docs path updates consistent (and make it a bit more robust)

  • generate-docs, Vale, and the failure diagnostic all reference ./docs/content/cli/master/command-reference.md consistently, so they’ll stay aligned.
  • The checked-out crossplane/docs repo contains content/cli/master/, so os.WriteFile(... ) shouldn’t fail due to a missing parent directory; optional safeguard: add mkdir -p ./docs/content/cli/master before generate-docs.
🤖 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 @.github/workflows/ci.yml at line 205, The CI step uses
./bin/linux_amd64/crossplane generate-docs -o
./docs/content/cli/master/command-reference.md but can fail if the target
directory is missing; ensure the job creates the parent directory first by
running a mkdir -p ./docs/content/cli/master before invoking the generate-docs
command and confirm any related Vale or failure-diagnostic steps continue to
reference the exact same ./docs/content/cli/master/command-reference.md path so
all references remain consistent.
🤖 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.

Nitpick comments:
In @.github/workflows/ci.yml:
- Line 205: The CI step uses ./bin/linux_amd64/crossplane generate-docs -o
./docs/content/cli/master/command-reference.md but can fail if the target
directory is missing; ensure the job creates the parent directory first by
running a mkdir -p ./docs/content/cli/master before invoking the generate-docs
command and confirm any related Vale or failure-diagnostic steps continue to
reference the exact same ./docs/content/cli/master/command-reference.md path so
all references remain consistent.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 0fae41d8-8e0a-499a-8636-9509af9a58a4

📥 Commits

Reviewing files that changed from the base of the PR and between dc7a1fa and 96e0b27.

⛔ Files ignored due to path filters (1)
  • cmd/crossplane/docs-templates/command-reference.md.tmpl is excluded by none and included by none
📒 Files selected for processing (3)
  • .github/workflows/ci.yml
  • CONTRIBUTING.md
  • cmd/crossplane/xpkg/init.go

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant