updating-changelog
Analyze PR changes to automatically generate and update migration notes and changelog documentation.
Install
mkdir -p .claude/skills/updating-changelog && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/3602" && unzip -o skill.zip -d .claude/skills/updating-changelog && rm skill.zipInstalls to .claude/skills/updating-changelog
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Updates changelog documentation for contract developers and node operators by analyzing branch changes relative to 'next'. Use when preparing a PR, updating migration notes, documenting breaking changes, or when asked to update changelog/release notes.Key capabilities
- →Analyze git diffs between development branches
- →Categorize changes into breaking, features, and deprecations
- →Draft release notes and migration entries
- →Format documentation for contract developers and node operators
How it works
The skill compares the current branch against the next branch to identify code changes, then formats these findings into specific markdown files following established project conventions.
Inputs & outputs
When to use updating-changelog
- →Draft release notes for a new PR
- →Update migration notes for contract changes
- →Document breaking API changes
- →Create changelog entries for node operators
About this skill
Updating Changelog
The docs live in this repository's docs/, in two lines that each have their own copy of
every developer and operator page (docs/CLAUDE.md, "Two dev lines: change both"). The code
they describe is mostly aztec-node's: main's pages follow aztec-node main at the commit
docs/aztec-node.json pins, and the v6 line's (docs/lines/v6/) follow aztec-node v6 at the
commit docs/lines/v6/aztec-node.json pins. Each is read through its line's checkout, which
node docs/scripts/aztec_node.mts fetch keeps (main's is $AZTEC_NODE_DIR, default
docs/.aztec-node/tree; v6's is docs/lines/v6/.aztec-node/tree); versions and changes are
read there, never in the labs/ submodule. This repository's own code (l1-contracts/,
barretenberg/, …) is the rest.
aztec-node records operator-facing changes as they land, in CHANGELOG-OPERATORS.md at its
root. It keeps one copy per release line, on that line's branch, so the checkout holds the copy
for the line the pin names. Those entries are the operator changelog's source: this skill moves
them here and re-heads them under the release, rather than reconstructing them from the diff.
The diff is still read, as the check on what the file missed.
Steps
1. Determine Target Files
The version is the Labs release the line's pin names, read from its checkout. For main
(for the v6 line, lineopt="--line v6"):
cd "$(git rev-parse --show-toplevel)"
lineopt=
node docs/scripts/aztec_node.mts $lineopt fetch && pin=$(node docs/scripts/aztec_node.mts $lineopt env) || exit 1
eval "$pin"
jq -r '."."' "$AZTEC_NODE_DIR/.version-manifest.json" 2>/dev/null ||
jq -r '."."' "$AZTEC_NODE_DIR/.release-please-manifest.json"
6.0.0 → edit v6.md. aztec-node renamed its manifest, so read whichever name the pinned
commit carries; both live in the checkout. It keeps one branch per release line — v6 ships
the 6.x line, main the next major — and the pin names a commit on one of them, so the version
this reports is the line being documented. The release-please manifest at this repository's
root versions the Foundation tree instead, whose numbers are unrelated to Labs': never take
the version from it.
Documenting one aztec-node PR (source 3 below) takes the major from the PR's line instead,
since a pin can lag it: baseRefName main is the major main carries (v7 from
2026-11-04), v6 is v6.
Which lines get the entry. A v6.x entry goes into both lines, since v7 readers upgrade from the latest v6. A v7 entry goes into main only. Released entries are history in either line: never edit them.
Target files, in each line that gets the entry (main's paths below; the v6 line's are the
same under docs/lines/v6/):
- Aztec contract developers:
docs/docs-developers/docs/resources/migration_notes.md - Node operators and Ethereum contract developers:
docs/docs-operate/operators/reference/changelog/v{major}.md
When that file is new (the first entry of a major), two more files of the same line must be updated or the page ships unreachable:
docs/docs-operate/operators/reference/changelog/index.md: add a### [<version>](./<page>.md)entry at the top of## Version history. The heading is the release (v6.0.0,v5.2.0,v4.3.x); the link target is the page's actual filename, which is not derived from the heading. Page names vary by how many releases a major has needed:v6.md,v5.2.md,v4.3.md,v4.2.md,v4.md,v2.0.2.mdall exist. Copy the filename you created; do not construct it from the version.docusaurus.config.jssetsonBrokenMarkdownLinks: "throw", so a link to a page that does not exist fails the build.docs/sidebars-operate.js: add"operators/reference/changelog/<page>"(the same filename, without.md) to the changelog list. The sidebar enumerates these pages explicitly; an unlisted page is published but has no nav entry.
Routing the Labs release notes (source 4 below, and the release skills). Route each entry by the section it sits in, into the target files above:
| Section of the notes | Goes to |
|---|---|
Breaking changes: Aztec.nr, Aztec.js, Node API, CLI (wallet and dev commands), Protocol | migration notes |
For wallet / PXE developers | migration notes, when a project on the previous version must change something |
Breaking changes for node operators, When to switch on Mainnet, Node operators under Breaking changes, For node operators (Publishers and L1, BLS keys and staking, Provers, Operations) | operator changelog |
| Where things live | by the entry's tag: [npm] and [Aztec.nr] to the migration notes, [Docker] to the operator changelog |
Security & correctness | operator changelog, only when an operator must act |
New in this release | operator changelog (its new-features shape) when operators see it; never the migration notes |
Protocol constants | neither: /release-docs Step 9 checks them against the chain |
Summary, Reference | neither |
These are v6.0.0's headings. Route a section the table does not name by who must act on each entry, and ask when that is unclear. The migration notes take what a project on the previous version must change, plus deprecations that still work; pure new features stay out. The operator changelog takes breaking changes, new features and changed defaults.
2. Analyze Branch Changes
The base is origin/next (git fetch origin next first). Four sources, each read where it
lives:
-
This repository's own changes (Foundation code, and the docs already written; the
labsgitlink is the Foundation's build input, not the docs' pin):cd "$(git rev-parse --show-toplevel)" git diff origin/next...HEAD --stat -- . ':!labs' git diff origin/next...HEAD -- . ':!labs' -
Labs code, when this branch moves a line's pin (
docs/aztec-node.jsonordocs/lines/<line>/aztec-node.json, moved withnode docs/scripts/aztec_node.mts [--line <line>] pin <tag>). Read the range in that line's checkout; both commits must be in it, and a two-commit diff needs no history between them. For main:cd "$(git rev-parse --show-toplevel)" pinfile=docs/aztec-node.json lineopt= # the v6 line's: pinfile=docs/lines/v6/aztec-node.json lineopt="--line v6" old=$(git show "$(git merge-base origin/next HEAD):$pinfile" | node -p 'JSON.parse(require("fs").readFileSync(0, "utf8")).commit') new=$(node -p "require('./$pinfile').commit") node docs/scripts/aztec_node.mts $lineopt fetch && pin=$(node docs/scripts/aztec_node.mts $lineopt env) || exit 1 eval "$pin" git -C "$AZTEC_NODE_DIR" fetch --depth 1 --no-tags origin "$old" "$new" git -C "$AZTEC_NODE_DIR" diff "$old" "$new" -- CHANGELOG-OPERATORS.md git -C "$AZTEC_NODE_DIR" diff --stat "$old" "$new" git -C "$AZTEC_NODE_DIR" diff "$old" "$new" -- yarn-project/ noir-projects/ <other paths> gh api "repos/aztec-labs-eng/aztec-node/compare/$old...$new" \ --jq '.total_commits, (.commits[].commit.message | split("\n")[0])' gh api "repos/aztec-labs-eng/aztec-node/compare/$old...$new" \ --jq '.commits[].commit.message | select(test("!:"))'The lines that diff adds to
CHANGELOG-OPERATORS.mdare the operator entries for this pin move, written by whoever made each change. Take them as they stand: the author knew what breaks. A pin whose$oldpredates the file has nothing to diff, so read the section whole instead:git -C "$AZTEC_NODE_DIR" show "$new:CHANGELOG-OPERATORS.md"Both commands come back empty for a pin either side of which predates the file; the commit scan is then the only source, as it was before.
Everything below is the check on what that file missed. The entry is a convention rather than something CI enforces, so a PR that renamed a flag without writing one still has to be documented. When the diff turns up such a change, say so: the entry is missing in aztec-node too, and the next person to read that file will not know the change happened.
aztec-node marks breaking changes only with the conventional-commit
!(feat!:,feat(txe)!:), never aBREAKING CHANGE:trailer. The second command prints every message containing!:, bodies included: port commits (chore: port … from monorepo) list the breaking commits they carry only in their body. The compare API lists at most 250 commits; whentotal_commitsis larger, list the PRs merged between the two commits' dates instead, and keep only those the diff confirms:from=$(git -C "$AZTEC_NODE_DIR" log -1 --format=%cs "$old") to=$(git -C "$AZTEC_NODE_DIR" log -1 --format=%cs "$new") gh pr list --repo aztec-labs-eng/aztec-node --state merged --limit 1000 \ --search "merged:$from..$to" --json number,title --jq '.[] | "\(.number) \(.title)"' -
One aztec-node PR, when asked to document a change that has not reached the pin yet:
gh pr view <PR_NUMBER> --repo aztec-labs-eng/aztec-node --json title,body,baseRefName,files,url gh pr diff <PR_NUMBER> --repo aztec-labs-eng/aztec-nodeWhen the PR touches
CHANGELOG-OPERATORS.md, that entry is what to document, and the branch the PR targets names the release line it belongs to. When it changes something operators configure and carries no entry, the entry is missing there: say so, so it can be added before the pin moves and the change has to be reconstructed from the diff alone. -
The Labs release notes, when this branch moves a line's pin to a release or rc tag of v6.1.0 or later (
v6.1.0-rc.1counts). They index what changed;docs/CLAUDE.md("Labs release notes") says how to treat them. The range starts at the newest released version in the line's migration notes, not at the old pin, which can be a nightly. For main:cd "$(git rev-parse --show-tople
Content truncated.
When not to use it
- →When changes are not relative to the next branch
Prerequisites
Limitations
- →Requires manual review of draft entries before file updates
- →Dependent on consistent use of component tags
How it compares
It automates the categorization and formatting of release notes based on project-specific documentation standards rather than manual drafting.
Compared to similar skills
updating-changelog side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| updating-changelog (this skill) | 1 | 9mo | Review | Intermediate |
| releasenotes | 1 | 5mo | No flags | Beginner |
| bd-to-br-migration | 1 | 10mo | Review | Intermediate |
| readme-sync | 0 | 5mo | Review | Beginner |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by AztecProtocol
View all by AztecProtocol →You might also like
releasenotes
exceptionless
Generate formatted changelogs from git history since the last release tag. Use when preparing release notes that categorize changes into breaking changes, features, fixes, and other sections.
bd-to-br-migration
Dicklesworthstone
Migrate docs from bd (beads) to br (beads_rust). Use when updating AGENTS.md, converting bd commands, "bd sync" → "br sync --flush-only", or beads migration.
readme-sync
hiroshi0530
|
pr-demo
mikeyobrien
Use when creating animated demos (GIFs) for pull requests or documentation. Covers terminal recording with asciinema and conversion to GIF/SVG for GitHub embedding.
tutorial-any-repo
TKONIY
Automatically generate a file-by-file code tutorial website for any repository. Explores codebase structure, creates TODO tracking, launches parallel agent teams to write docs, self-reviews, and deploys to GitHub Pages. Use when user says "write a tutorial for this project", "explain this codebase",
ml-paper-writing
davila7
Write publication-ready ML/AI papers for NeurIPS, ICML, ICLR, ACL, AAAI, COLM. Use when drafting papers from research repos, structuring arguments, verifying citations, or preparing camera-ready submissions. Includes LaTeX templates, reviewer guidelines, and citation verification workflows.