docs: add changelog guidelines and align the /changelog prompt#10867
Merged
Conversation
The drafted entries drifted from CHANGELOG_GUIDELINES: inconsistent section headings, missing PR links, em dashes, and a broken code fence, and one enum addition was filed under Added when it is breaking. The prompt inverted the breaking-enum rule (it named non-exhaustive enums, the safe case) and never described the operator-plus-per-crate changelog structure, so the model reinvented the layout each run. State the two-changelog structure and output shape, require the PR link and exact `### ` headings, correct the breaking rule to a new variant on an enum that is not `#[non_exhaustive]`, separate operator-breaking from crate-breaking, add the Fixed-versus-Changed test, and forbid em dashes and extra code fences.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR rewrites the natural-language prompt used by the /changelog GitHub Actions command (changelog-command.yml) so that Claude-drafted changelog entries follow Zebra's actual conventions. It encodes the two-tier changelog structure (operator root CHANGELOG.md plus one block per affected crate), a fixed output shape, a required PR link on every entry, exact ### Keep-a-Changelog section headings, and — most importantly — corrects the breaking-change rule so that a new variant on an enum that is not #[non_exhaustive] (rather than the previously-named non-exhaustive case) is flagged as breaking. It also separates operator-breaking from crate-breaking changes, adds a Fixed-vs-Changed test, and forbids em dashes and stray code fences.
The change is confined to prompt text; no code paths, permissions, or workflow triggers are altered. The corrected Rust semantics are accurate, and the encoded structure/section ordering matches the repo's existing changelog files. The one issue is an internal contradiction in the new prompt wording (see below).
Changes:
- Restructure the drafting prompt to state the operator-root + per-crate changelog layout and a fixed output shape.
- Correct the breaking-change definition to target non-
#[non_exhaustive]enums, and split operator-breaking from crate-breaking criteria. - Require a PR link per entry, exact
###headings, the Fixed-vs-Changed test, and ban em dashes/extra code fences.
CONTRIBUTING.md, AGENTS.md, and the PR template pointed at a root CHANGELOG_GUIDELINES.md that never existed. Add the guidelines as a book dev page next to the release process, list it in SUMMARY.md, and repoint the references. A note on the /changelog prompt marks the page as the source its rules distill, so the two stay in sync.
gustavovalverde
changed the title
Address review feedback that one bullet per changelog file contradicts the repo's own convention: a single PR routinely produces several entries in one file, and a breaking-yet-additive change (a new variant on an enum that is not non_exhaustive) is listed under both Breaking Changes and Added, as zebra-state does for the AnyChainBlock variants. Draft one bullet per distinct change, dual-list such additions, record the same convention in the guidelines, and point the release notes prompt at the GitHub Release Format section so both prompts track the doc.
The page still said one entry per PR and one section only, which the prompt (now per distinct change) and the repo contradict: PR #10798 alone carries three entries across Fixed and Security. Relax the page to one entry per distinct change, with a PR of several independent changes getting one entry each, so the page, the prompt, and the existing changelogs agree. The anti-padding and anti-grouping examples stand, and section priority now scopes to a single change.
gustavovalverde
changed the title
/changelog prompt
The step produces the summary and Update Priority parts of the GitHub Release Format, not the full format; How to Upgrade and Compatibility are added at release time. Correct the comment so it does not overstate the step.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
mpguerra
approved these changes
Jul 1, 2026
mpguerra
left a comment
mpguerra
left a comment
Contributor
There was a problem hiding this comment.
Good enough for now, can revisit and iterate on this if necessary :)
Contributor
Merge Queue Status
This pull request spent 11 minutes 38 seconds in the queue, including 47 seconds running CI. Required conditions to merge
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation
Two related gaps.
CONTRIBUTING.md,AGENTS.md, and the PR template all point contributors at aCHANGELOG_GUIDELINES.mdthat never existed in the tree. And the/changelogcommand's drafts drift from those (unwritten) rules: section headings alternate between### Fixedand bold**Fixed**, PR links appear on some entries and not others, some drafts use em dashes or nest a code fence, and on #10820 the two newReadRequestvariants land under### Addedin the crate changelog thoughReadRequestis not#[non_exhaustive], so adding a variant is breaking for crate consumers.Solution
Commit the guidelines and align the automation to them from one source.
book/src/dev/changelog-guidelines.md) next to the release process, list it inSUMMARY.md, and repointCONTRIBUTING.mdandAGENTS.mdat it./changelogprompt to encode the rules it kept missing: the operator-plus-per-crate structure and a fixed output shape, required PR links and exact###headings, the corrected breaking rule (a new variant on an enum that is not#[non_exhaustive], not the reverse), operator-breaking versus crate-breaking, the Fixed-versus-Changed test, and no em dashes or extra code fences.AI Disclosure
AI tools were used: Claude analyzed the drafts against the guidelines, transcribed the guidelines, and wrote the prompt.