| name | generate-changelog |
| description | Generate changelog entries from merged PRs since the last release. Fetches PR data, classifies changes as normal or breaking, presents for user review, and optionally creates a PR with the updates. |
Changelog Generator
Generate changelog entries by analyzing merged PRs since the last release.
Execute these phases in order:
- Data Gathering — find last release, fetch PRs, classify, generate entries
- Changelog Update — write entries into CHANGELOG.md
- Review & Approval — present the actual diff to the user for review
- PR Creation (optional) — push and create PR, only if the user requests it
Phase 1: Data Gathering
Step 1.1: Find the latest release tag
Run:
git tag --sort=-creatordate | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -1
Record as LAST_TAG. Get the tag's date:
git log -1 --format=%aI $LAST_TAG
Record as TAG_DATE.
Step 1.2: Extract category tags from existing CHANGELOG.md
Read CHANGELOG.md and extract all unique [tag] patterns from changelog entries (pattern: - [tag] ...). Build a deduplicated vocabulary list preserving original casing.
Step 1.3: Fetch merged PRs since the last release
gh pr list --state merged --search "merged:>TAG_DATE" --json number,title,author,body,labels,mergedAt --limit 100
Use the date portion only from TAG_DATE (e.g. 2026-02-09).
Step 1.4: Filter PRs
Skip rules (in order):
- PR has the
changelog label → skip (already tracked in a previous changelog update)
- Author login is
dependabot or dependabot[bot] → skip
- Title matches version bump patterns → skip:
- Starts with
Switch to and contains -next
- Title is a bare version like
vX.Y.Z
- Title starts with
Release v
- Title contains
update changelog (case insensitive) → skip
- Title is purely CI/metadata (readme badges, workflow config) AND body does NOT contain
[x] This PR should be mentioned in the changelog → skip
Override: If the PR body contains [x] This PR should be mentioned in the changelog, always include it regardless of rules 3-5. PRs with the changelog label (rule 1) and dependabot PRs (rule 2) are always skipped.
Step 1.5: Classify each PR
- If body contains
[x] This PR introduces a breaking change → breaking
- If body contains
[ ] This PR introduces a breaking change → normal
- If no checkbox info, analyze title and body:
- Breaking keywords: "refactor", "rename", "remove", "replace", "migrate", "breaking", "deprecate"
- Clearly non-breaking (bug fix, docs, minor enhancement) → normal
- Uncertain → flag for user review
Step 1.6: Assign category tags
Pick the most fitting tag from the vocabulary (Step 1.2) based on PR title and body. If no tag fits, mark as uncertain: [???/best-guess].
Step 1.7: Generate changelog entries
Entry Format
Normal changes:
- [tag] Description [#N](https://github.com/OWNER/REPO/pull/N)
Breaking changes with migration sub-items:
- [tag] Description [#N](https://github.com/OWNER/REPO/pull/N)
- Migration detail 1
- Migration detail 2
Multiple PRs for the same change:
- [tag] Description [#N](url) [#M](url)
Style Guide
Formatting:
- Entry prefix:
- (dash + exactly 3 spaces)
- Sub-item indent: 4 spaces +
- (4 spaces from parent dash)
- Sub-sub-item indent: 8 spaces +
-
- Single space between
[tag] and description text
- Single space before PR link at end of line
- PR links are mandatory, full URLs:
[#123](https://github.com/OWNER/REPO/pull/123)
Wording:
- Always start with a present tense imperative verb (not past tense)
- Common verbs: Fix, Improve, Add, Update, Extend, Ensure, Introduce, Remove, Refactor, Rename, Provide, Allow, Support
- Bug fixes: "Fix a bug that caused/prevented...", "Fix X behavior"
- Features: "Introduce...", "Add support for...", "Provide..."
- Enhancements: "Improve...", "Extend...", "Ensure that..."
- Refactors: "Refactor...", "Rework...", "Rename..."
- Be specific — never "Fix various issues"
Capitalization:
- Tags are always lowercase:
[diagram], not [Diagram]
- Description starts lowercase after the tag (unless proper noun or code element)
- Section headers: Title Case (
### Potentially Breaking Changes)
Description cleanup from PR title:
- Remove issue tracker prefixes (e.g.
GLSP-1234:, GH-123:, ISSUE-456:)
- Remove conventional commit prefixes:
fix:, feat:, chore:
- Rephrase bug-report style to changelog style:
- BAD: "Edit label UI does not resize on graph zoom"
- GOOD: "Fix edit label UI not resizing on graph zoom"
- Keep concise — one line
Breaking changes:
- Describe what changed, why it's breaking, and how to migrate
- Extract migration sub-items from the PR body's "What it does" section
Phase 2: Changelog Update
Step 2.1: Determine the version section
Read CHANGELOG.md in the repository root.
Active section detection:
- An active section has the
- active suffix (e.g. ## v2.7.0 - active)
- If an active section exists → merge new entries into it
- If the topmost section is a released version (no
- active suffix) → create a new active section above it
Creating a new section:
- Bump the minor version of
LAST_TAG (e.g. v2.6.0 → v2.7.0)
- Insert after the title line, before the first
## heading:
## v2.7.0 - active
### Changes
- [tag] Entry [#N](url)
### Potentially Breaking Changes
- [tag] Entry [#N](url)
- Sub-item detail
Only include "Potentially Breaking Changes" if there are breaking entries.
Merging into existing active section:
- Check PR numbers against existing entries to avoid duplicates
- Append new entries to the appropriate subsection
- Create missing subsections as needed
Step 2.2: Write the updated CHANGELOG.md
Use the Edit tool to update CHANGELOG.md directly in the current working tree. Match existing formatting conventions.
Phase 3: Review & Approval
Step 3.1: Show the diff
git diff CHANGELOG.md
Present the diff to the user.
Step 3.2: Prompt for uncertain items
List any entries flagged as uncertain (category or breaking status) and ask the user to resolve them.
Even if nothing is uncertain, ask:
"Does everything look correct, or would you like to adjust any entries?"
Step 3.3: Collect user feedback
- Approve as-is → done (or proceed to Phase 4 if PR was requested)
- Request edits → apply changes, show updated diff, ask again
- Resolve uncertain items → apply, show updated diff
Do NOT proceed to Phase 4 unless the user explicitly requests a PR.
Phase 4: PR Creation (Optional)
Only execute this phase if the user explicitly requests a PR (either in their initial prompt or after reviewing the changelog). If the user hasn't mentioned a PR, ask after approval:
"Would you like me to create a PR for this changelog update, or are you done?"
Step 4.1: Determine the branch name
Check if changelog-update exists on remote:
git ls-remote --heads origin changelog-update
If it exists, increment: changelog-update-2, changelog-update-3, etc.
Step 4.2: Create branch, commit, and push
git checkout -b BRANCH_NAME
git add CHANGELOG.md
git commit -m "Update changelog"
git push -u origin BRANCH_NAME
Step 4.3: Create the PR
If the repo has a .github/PULL_REQUEST_TEMPLATE.md, use its structure to fill in the PR body. Otherwise use a simple body describing the changelog update.
Report the PR URL.
Step 4.4: Label referenced PRs
Add the changelog label to every PR mentioned in the new entries:
gh pr edit PR_NUMBER --add-label "changelog"
Report which PRs were labeled.
