Update Docs From Commits

Filter to commits that are likely to affect docs. Look for these signals:

1. Commit type: feat, fix, refactor, perf commits often change behavior. docs commits are already doc changes. chore, ci, test commits rarely need doc updates.
2. Files changed: Changes to crates/openshell-cli/, python/, proto/, deploy/, or policy-related code are high-signal.
3. Ignore: Changes limited to tests/, e2e/, .github/, tasks/, or internal-only modules.

# Show files changed per commit to assess impact
git log v0.2.0..HEAD --oneline --no-merges --name-only

Step 2: Map Commits to Doc Pages

For each relevant commit, determine which doc page(s) it affects. Use this mapping as a starting point:

If a commit does not map to any existing page but introduces a user-visible concept, flag it as needing a new page.

Step 3: Read the Commit Details

For each commit that needs a doc update, read the full diff to understand the change:

git show <commit-hash> --stat
git show <commit-hash>

Extract:

• What changed (new flag, renamed command, changed default, new feature).
• Why it changed (from the commit message body, linked issue, or PR description).
• Any breaking changes or migration steps.

Step 4: Read the Current Doc Page

Before editing, read the full target doc page to understand its current content and structure:

# Read the file

Identify where the new content should go. Follow the page's existing structure.

Step 5: Draft the Update

Write the doc update following the rules in docs/CONTRIBUTING.mdx. Key reminders:

• Active voice, present tense, second person.
• No unnecessary bold. Reserve bold for UI labels and parameter names.
• No em dashes unless used sparingly. Prefer commas or separate sentences.
• Start sections with an introductory sentence that orients the reader.
• No superlatives. Say what the feature does, not how great it is.
• Code examples use shell language for copyable commands, with no $ prompt prefix.
• Use text fences for transcripts, logs, or shell sessions that should not be copied verbatim.
• Include the SPDX header as YAML comments in frontmatter if creating a new page.
• Match existing Fern frontmatter format if creating a new page, including sidebar-title, keywords, and position when they are relevant. Use frontmatter slug only for folder-discovered pages or absolute URL overrides.
• Use sidebar-title for short nav labels. For explicit navigation entries, keep relative slug values in docs/index.yml instead of page frontmatter.
• Keep explicit page: entries in docs/index.yml. Fern still requires them. If the page defines sidebar-title, set page: to that value. Otherwise set page: to the page frontmatter title.
• Use skip-slug: true in docs/index.yml when a child page should live at the parent section path.
• Use keywords as a comma-separated string.
• Do not add a duplicate H1. Fern renders the page title from frontmatter.
• Always write NVIDIA in all caps. Wrong: Nvidia, nvidia.
• Always capitalize OpenShell correctly. Wrong: openshell, Openshell, openShell.
• Do not number section titles. Wrong: "Section 1: Deploy a Gateway" or "Step 3: Verify." Use plain descriptive titles.
• No colons in titles. Wrong: "Gateways: Deploy and Manage." Write "Deploy and Manage Gateways" instead.
• Use colons only to introduce a list. Do not use colons as general-purpose punctuation between clauses.

When updating an existing page:

• Add content in the logical place within the existing structure.
• Do not reorganize sections unless the change requires it.
• Update any cross-references or "Next Steps" links if relevant.

When creating a new page:

• Follow the frontmatter template from docs/CONTRIBUTING.mdx.
• Add the page to the appropriate section in docs/index.yml.

Step 6: Present the Results

After drafting all updates, present a summary to the user:

## Doc Updates from Commits

### Updated pages
- `docs/sandboxes/manage-gateways.mdx`: Added `--gpu` flag documentation (from commit abc1234).
- `docs/reference/policy-schema.mdx`: Updated network policy schema for new `tls_inspect` field (from commit def5678).

### New pages needed
- None (or list any new pages created).

### Commits with no doc impact
- `chore(deps): bump tokio` (abc1234) — internal dependency, no user-facing change.
- `test(e2e): add gateway timeout test` (def5678) — test-only change.

Step 7: Build and Verify

After making changes, validate the Fern docs locally:

mise run docs

If a human needs to inspect rendering while iterating, they can also run:

mise run docs:serve

Check for:

• Validation warnings or errors.
• Broken cross-references.
• Correct rendering of new content in the PR preview when available.

Tips

• When in doubt about whether a commit needs a doc update, check if the commit message references a CLI flag, config option, or user-visible behavior.
• Group related commits that touch the same doc page into a single update rather than making multiple small edits.
• If a commit is a breaking change, add a note at the top of the relevant section using a Fern <Warning> callout.
• PRs that are purely internal refactors with no behavior change do not need doc updates, even if they touch high-signal directories.

Example Usage

User says: "Catch up the docs for everything merged since v0.2.0."

1. Run git log v0.2.0..HEAD --oneline --no-merges --name-only.
2. Filter to feat, fix, refactor, perf commits touching user-facing code.
3. Map each to a doc page.
4. Read the commit diffs and current doc pages.
5. Draft updates following the style guide.
6. Present the summary.
7. Run mise run docs to verify.