update-changelog
Skill119 starsChanged 3 months agoMITView on GitHub
Update CHANGELOG.md comprehensively based on git tags, merged PRs, and actual code diffs. Use when the user asks to "update the changelog", backfill missing versions, prepare a release, or reconcile [Unreleased] entries against shipped tags. Produces Keep-a-Changelog entries that describe user-facing impact, not implementation details.
- Reads credentials
- Commits and pushes
36 other projects use a version of this.
Adopted by
Most recently taken up by
- harshitsinghbhandari/domain-expansiontheir own version, first seen Nov 8, 2026
- Raicuparta/rai-paltheir own version, first seen Nov 2, 2026
- dotnet/vscode-csharptheir own version, first seen Nov 1, 2026
- a2ui-project/a2uitheir own version, first seen Nov 1, 2026
- raine/skillstheir own version, first seen Nov 1, 2026
- AcKeskin/contexturetheir own version, first seen Nov 1, 2026
Used with
Projects with it also use clack-cli-patterns, drag-to-reorder and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
openchamberSkillclack-cli-patterns
Use when creating or modifying OpenChamber CLI commands, prompts, terminal output, non-TTY behavior, `--quiet`, or `--json` behavior.
Also in 3 projects that use this
openchamberSkilldrag-to-reorder
Use when implementing or modifying OpenChamber sortable or drag-to-reorder behavior, especially `@dnd-kit`, touch/mobile interactions, variable-width items, or wrapping layouts.
Also in 3 projects that use this
mitsuhikoSkilloebb-scotty
Austrian rail travel planner (ÖBB Scotty). Use when planning train journeys in Austria, checking departures/arrivals at stations, or looking for service disruptions. Covers ÖBB trains, S-Bahn, regional trains, and connections to neighboring countries.
Also in 3 projects that use this
- +9 more from openchamber
Other versions36 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 36
- penpot/penpot★ 62ksame name
- alibaba/page-agent★ 29ksame name
- joke2k/faker★ 19ksame name
- a2ui-project/a2ui★ 17ksame name
- google/A2UI★ 17ksame name
- quickwit-oss/tantivy★ 16ksame name
- btriapitsyn/openchamber★ 13ksame name
- openchamber/openchamber★ 13ksame name
- mitsuhiko/agent-commands★ 3.2ksame name
- mitsuhiko/agent-stuff★ 3.2ksame name
26 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository5 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- loki-logsSkill
- silk-debugSkill
- updating-depsSkill
- whats-newSkill
The file
We split this skill into the rules it gives an agent
5 rules. 0 are common, 1 is distinctive, and 4 are very specific to this project.
0
Common
Most of the 35 edited versions we read keep these.
1
Distinctive
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 72
Verify the user-facing surface:
- Very specific: line 80
If the diff is purely internal (renames, helper extraction, type hints, test reorg) and there is no observable change, drop it — even if …
- Very specific: line 117
No author/PR-number/issue-number references — those live in commit history and PRs.
- Very specific: line 123
When promoting [Unreleased] to a version: copy the content under a new ## [X.Y.Z] - <tag-date> heading and leave [Unreleased] empty.
- Very specific: line 137
Do not run make release or push tags — the skill only edits CHANGELOG.md.
“Common” is measured: kept by at least 6 in 10 of the 35 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Update Changelog
Maintains CHANGELOG.md (Keep a Changelog format, semver) by reconciling it against git tags, merged PRs, and actual code diffs.
Format conventions (this repo)
- Header:
## [X.Y.Z] - YYYY-MM-DDfor released versions,## [Unreleased]at the top. - Section order: Added, Changed, Fixed, Deprecated, Removed, Security. Omit empty sections.
- Bullets describe user/operator/API-consumer impact, not internal refactors. Drop pure CI/test/lint commits unless they change observable behavior.
- Major features get a bold prefix:
- **VAT Support**: Complete VAT handling for ticket sales…. Optional nested sub-bullets for sub-features. - Bug fixes name the symptom that was fixed, not the patch ("
location_maps_urlmax length increased from 200 to 2048 to accommodate long Google Maps URLs"). - Dates are the tag date (committer date of the tag), not today's date.
Release model (this repo)
make releaserunsgh release create v$VERSION --generate-notesusingversionfrompyproject.toml.- A "bump X.Y.Z" PR (often bundled with small fixes — e.g.
chore: bundled fixes (...) + bump 1.55.0) lands onmain, thenmake releaseis invoked. - CHANGELOG.md must be updated in the same commit that bumps
pyproject.toml— write the new## [X.Y.Z] - YYYY-MM-DDsection before the bump PR is merged.
Workflow
1. Establish state
git tag --sort=-v:refname | head -20 # latest tags
grep -E '^## \[' CHANGELOG.md | head -10 # versions present in changelog
grep '^version = ' pyproject.toml # pending versionCompare the three. Common situations:
- Behind on tags — CHANGELOG missing released versions → backfill each gap (step 2 per gap).
[Unreleased]populated, pyproject bumped — promote[Unreleased]to## [X.Y.Z] - <tag-date>and start a fresh empty[Unreleased].- New work since last tag — add entries to
[Unreleased]only.
2. Gather changes between two refs
For each version gap vA..vB (or vLast..HEAD for unreleased):
# 1. Tag date for the section header
git log -1 --format=%cs vB # YYYY-MM-DD
# 2. Merged PRs in the range (richest signal — PR titles are usually user-facing)
git log vA..vB --merges --format='%h %s' --first-parent
# 3. Full commit subjects on main (catch non-PR commits)
git log vA..vB --format='%h %s' --first-parent
# 4. For each non-trivial PR, read its body for the user-facing description
gh pr view <number> --json title,body,labelsGroup commits by prefix (feat:, fix:, refactor:, chore:, test:, docs:, ci:) as a first pass — but do not trust the prefix alone (see step 3).
3. Verify impact from the diff
A commit message says what the author intended; the diff says what actually changed. For any entry where impact is unclear or the message is terse:
git show <sha> --stat # which files moved
git show <sha> -- <interesting-path> # the actual change
git diff vA..vB -- src/<app>/ # cumulative for a subsystemVerify the user-facing surface:
- New endpoints / changed schemas → check
events/controllers/,accounts/controllers/,*/schema/,openapi.jsonif regenerated. - New models or migrations → check
*/models/,*/migrations/00XX_*.py(squashed migrations matter for ops). - Settings or env vars → check
src/revel/settings/,.env*,CLAUDE.md. - Background jobs / Celery → check
*/tasks.py,celery.pybeat schedule. - Permissions / auth → check
events/controllers/permissions.py,common/auth/.
If the diff is purely internal (renames, helper extraction, type hints, test reorg) and there is no observable change, drop it — even if the commit was feat:-prefixed.
4. Categorize
| Section | Use for |
| Added | New features, new endpoints, new models, new settings/flags, new notification channels, new file format support |
| Changed | Behavior changes to existing features, API contract changes (non-breaking), default-value changes, performance changes visible to users |
| Fixed | Bug fixes — describe the symptom |
| Deprecated | Features still working but slated for removal |
| Removed | Removed features, endpoints, settings |
| Security | Auth fixes, permission tightenings, vulnerability patches (do not name the CVE if not public) |
Bundle related commits into one bullet. A feature that spans 5 PRs becomes one bold-prefixed bullet, optionally with sub-bullets per sub-feature.
5. Write entries
Style examples lifted from this repo's existing entries — match the voice:
### Added
- **Referral System — Full Launch**: Complete referral program with Stripe auto-payouts
- `UserBillingProfile` model for referrer billing details (VAT ID, address, self-billing agreement)
- Monthly payout calculation task aggregating net platform fees per referral
- VAT preview endpoint for checkout (`POST /events/{event_id}/tickets/vat-preview`) with buyer-specific VAT calculation and VIES caching (Redis, 30-minute TTL)
### Fixed
- Unbanning a user now clears the stale `BANNED` `OrganizationMember` row that the ban created.
- Follower notifications (`NEW_EVENT_FROM_FOLLOWED_ORG`) no longer sent for non-public eventsRules:
- Lead with the what, not the how. ("Discord admin-ping channel" not "Added
discord_admin_webhook_urlsetting andsend_discord_admin_pingfunction"). - Backticks for code symbols (model names, field names, env vars, endpoints).
- Bold prefix
**Name**:only for headline features that warrant top-billing. - One sentence per bullet; sub-bullets for multi-part features.
- No author/PR-number/issue-number references — those live in commit history and PRs.
6. Insert into the file
[Unreleased]always stays at the top, even if empty (with no subsections), so future entries have a home.- New released sections go directly under
[Unreleased], in descending version order. - When promoting
[Unreleased]to a version: copy the content under a new## [X.Y.Z] - <tag-date>heading and leave[Unreleased]empty. - Preserve any existing
[Unreleased]entries — they may already document work in the new version.
7. Verify
# Visual diff
git diff CHANGELOG.md
# Sanity check: every tag from vA..latest has a section
git tag --sort=-v:refname | head -20
grep -E '^## \[' CHANGELOG.mdDo not run make release or push tags — the skill only edits CHANGELOG.md. The user runs make release themselves.
Anti-patterns
- ❌ Dumping every commit subject as a bullet. Filter, group, rewrite.
- ❌ Using the date of editing as the section date — use the tag's commit date.
- ❌ Trusting
feat:/fix:prefixes without checking the diff. - ❌ Mentioning internal refactors, test additions, type fixes, or CI changes unless they affect users/operators.
- ❌ Inventing impact you can't confirm from the diff. If unsure, ask the user or omit.
- ❌ Overwriting existing
[Unreleased]content when promoting it — merge, don't replace. - ❌ Editing
pyproject.tomlor creating tags. Out of scope for this skill.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

