Skip to content

docs(release-docs): reconcile next docs changes into newly cut version#24235

Open
critesjosh wants to merge 2 commits into
nextfrom
docs/release-docs-reconcile-next-changes
Open

docs(release-docs): reconcile next docs changes into newly cut version#24235
critesjosh wants to merge 2 commits into
nextfrom
docs/release-docs-reconcile-next-changes

Conversation

@critesjosh

Copy link
Copy Markdown
Contributor

What

Rewrites Step 14 of the release-docs skill (.claude/skills/release-docs/SKILL.md) to reliably catch documentation changes that landed on next but won't be present in a version cut from the release tag.

Why

A new docs version (e.g. 5.1.0) is cut from the release tag, which is older than next. Any docs work merged into next after the tag is therefore missing from the freshly cut snapshot. The previous Step 14 gestured at this but had two gaps:

  1. It only inspected source docs, never the existing versioned snapshots. A fix merged directly into the previous version's snapshot on next (e.g. developer_versioned_docs/version-v5.0.0-rc.1/...) was never reviewed.
  2. It diffed the working tree against the new snapshot. Since the working tree is checked out at the release tag, that diff compared tag-source against a snapshot just cut from the same source — near-identical, and blind to what actually diverged on next.

Changes

  • Reframe Step 14 ("Reconcile next Docs Changes Into the New Version") to explain the tag-vs-next divergence up front.
  • Call out the two classes of missed change explicitly: source/current docs and fixes applied directly to the previous versioned snapshot.
  • Diff against origin/next (not the working tree): git log v<new>..origin/next -- docs/, plus per-area diffs for source docs and the previous snapshot directory.
  • Add a Key Points bullet flagging this as the most commonly missed step.

The new docs version is cut from the release tag, which predates docs
changes merged into next. Rewrite Step 14 to diff the tag against
origin/next and backport relevant changes — covering both the source
docs and fixes applied directly to the previous versioned snapshot, the
latter of which the prior wording never inspected.
…config

Steps 5 and 13 overwrite the local version configs with the new version
before Step 14 runs, so reading <prev_version> from the working-tree
config would yield the new version and point the snapshot diff at the
wrong directory. Read it from origin/next instead.
@critesjosh critesjosh marked this pull request as ready for review June 23, 2026 14:08
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