docs: Release-As is always the current version plus one patch; a behaviour-changing refactor is not a hidden type - #74
Conversation
…ule 2; drop the refactor example Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> (cherry picked from commit 5155034)
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: aca01cf990
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| "No version bump" means release-please does not open a release PR for it at | ||
| all — it is a hidden type. A change users will notice that only fits a hidden | ||
| type (a new CI gate under `ci`, a behaviour-changing `refactor`) still has to | ||
| ship: put a `Release-As: X.Y.Z` footer in the PR body (the body becomes the | ||
| squash commit's message) and release-please cuts that version. | ||
| all — it is a hidden type, and it is also left out of the changelog. So first |
There was a problem hiding this comment.
When a non-triggering commit carries Release-As, release-please can still render that commit in the generated changelog. This repository already demonstrates the opposite of the new guidance: docs: commit 819ce60 used Release-As: 0.5.2, and CHANGELOG.md lines 6–8 include it under “Documentation.” Conflating “does not trigger a release” with “is omitted from the changelog” will therefore mislead maintainers; document these as separate behaviors.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Right, and verified in the source: conventional-changelog-conventionalcommits writer-opts.js sets discard = false for any commit whose footer or body matches Release-As, so the carrier is rendered under its type's section whatever the type, while the other hidden-type commits in the range stay out. Both skills now say exactly that, plus the consequence this repository already shows — v0.5.2's changelog names the docs follow-up that carried the footer and not the CI gate it released — and tell the author to put the footer on the PR that is the change (9b0caf8).
…tever its type
Hidden-type commits are omitted from the generated changelog, but the one
that carries the `Release-As` footer is not: conventional-changelog's
conventionalcommits writer un-discards it ("Add an entry in the CHANGELOG
if special Release-As footer is used", writer-opts.js). v0.5.2 shows the
consequence — the changelog lists the docs follow-up that carried the
footer and not the CI gate it released. Say so, and say the footer goes on
the PR that is the change.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9b0caf82d2
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| the body becomes the squash commit's message — with X.Y.Z the current version | ||
| plus one patch; anything larger means the type was wrong (see |
There was a problem hiding this comment.
When a release PR already contains an unreleased feat or breaking commit, this unconditional patch-only recipe can under-version the whole release: Release-As overrides release-please's normal version calculation for the accumulated commit range, so a later hidden-type PR specifying the current version plus one patch can turn a pending minor or major release into a patch. Require checking the unreleased commits or merging the existing release first rather than saying that any larger version proves the hidden commit's type was wrong.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Agreed — buildNewVersion returns the footer's version for the whole range whenever any commit carries it. Both skills now say to use the footer only when no release is pending, and that with a release PR already open the hidden-type change should simply ride along without a footer (or the pending release be merged first) (0a058ea).
…s the computed version for the whole range Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0a058eafa9
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| the body becomes the squash commit's message — with X.Y.Z the current version | ||
| plus one patch; anything larger means the type was wrong (see |
There was a problem hiding this comment.
For a freshly de-templated adopter repository, no current release exists: docs/setup/bootstrap.md resets the manifest to 0.0.0 and deliberately configures the first release as 0.1.0, including Release-As: 0.1.0 as the immediate-release recipe. Applying this new unconditional “current version plus one patch” rule either yields an undefined version or incorrectly suggests 0.0.1; carve out the first release and use the configured initial-version there.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Added to rule 2: before the first release there is no current version — that release is numbered by initial-version (0.1.0 here, per docs/setup/bootstrap.md), so a footer there names that version. (bootstrap.md does not itself recommend a Release-As: 0.1.0 footer; the first feat/fix triggers v0.1.0 without one.) (21df179)
| `skills/release-management` rule 2). Only do this when no release is already | ||
| pending: the footer overrides the computed version for every commit since the | ||
| last tag, so with a release PR open (an unreleased `feat` or `fix`) a patch | ||
| footer would under-version it — leave the footer out and let the change ride |
There was a problem hiding this comment.
This repeats the full Release-As policy in branch-and-commit while also pointing to the same policy in release-management, contrary to the one-home/link-not-copy rule in skills/docs-hygiene/SKILL.md. The copies already differ over whether merging the pending release first is an option, and corrections such as the first-release exception can now leave contradictory agent guidance; keep the complete rule in release-management and make this section only link to it.
AGENTS.md reference: AGENTS.md:L73-L73
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Done: branch-and-commit rule 3 now only says hidden types ship nothing and points at release-management rule 2 for the Release-As recipe, its limits and the changelog exception; the full rule lives in one place (21df179).
…rst-release clause branch-and-commit rule 3 now points at release-management rule 2 instead of restating it (docs-hygiene rule 2, one home per fact). Rule 2 gains the first-release case: there is no current version before the first release, which `initial-version` numbers. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
1 participant
Summary
Re-lands commit
5155034, the answer to Codex's two P2 findings on #71, which was pushed after #71 had already been squash-merged and its branch deleted, so it never reachedmain. Cherry-picked verbatim (-x).skills/branch-and-commitrule 3: drop "a behaviour-changingrefactor" as an example of a hidden-type change that ships viaRelease-As— a refactor that changes behaviour is afixor afeat. Say first that a change users notice is usually not a hidden type at all, and bound the footer:X.Y.Zis the current version plus one patch, pointing at release-management rule 2.skills/release-managementrule 2 ("version bump is derived, not chosen"): state the one exception — a genuinely hidden-type change that adopters must pick up — with the same patch-only bound, and note that a hidden type also keeps the change out of the changelog. The pitfall now refers to rule 2 instead of restating the recipe.Docs only, hidden type, no release.
Related issue
Closes #73
Validation
Pick validation depth by blast radius. A level that applies but could not run becomes a
RISK:line below. See AGENTS.md for the validation ladder.make lintmake test(placeholder target;make checkruns the node tests, both green)Risk / rollback
Checklist
Before merging:
<type>: <description>)*.local.mdfiles committed