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-DD for released versions, ## [Unreleased] at the top.
- Section order: Added, Changed, Fixed, Deprecated, Removed, Security. Omit empty sections.
- Bullets describe user-facing impact (what an event organizer, attendee, or admin sees), not internal refactors. Drop pure CI/test/lint/type-fix commits unless they change observable behavior.
- Major features get a bold prefix:
- **Discount codes**: full admin CRUD…. Optional nested sub-bullets for sub-features.
- Bug fixes name the symptom that was fixed, not the patch ("Tier prices no longer get corrupted on save under non-English browser locales").
- Backticks for code symbols: routes (
/org/[slug]/admin/financials), component names, prop/flag names (is_open_ended, max_tickets_per_user), env vars (PUBLIC_API_URL).
- Dates are the tag date (committer date of the tag), not today's date.
- A version with no user-facing change still gets a header followed by:
_Maintenance release — internal, tooling, or dependency changes only._
Release model (this repo)
- The frontend mirrors the backend:
v-prefixed semver tags, version in package.json (not pyproject.toml), released via make release.
- A "bump X.Y.Z" commit (often bundled with small fixes) lands on
main, then the tag is pushed and the release created.
- CHANGELOG.md should be updated in the same commit that bumps
package.json — write the new ## [X.Y.Z] - YYYY-MM-DD section before the bump is merged.
⚠️ Repo-specific gotchas
- Always pass
-c log.showSignature=false to git (e.g. git -c log.showSignature=false log …). Commits are GPG-signed and signature-verification noise otherwise floods every git log/git show.
- Mixed merge styles. Early history uses real merge commits; recent history uses squash merges with the PR number in the subject (
feat(x): … (#498)). So gather commits with --first-parent on the full commit list — do not rely on --merges (it misses every squash merge).
- API-client noise. Most feature commits bundle a large regeneration of
src/lib/api/ (pnpm generate:api output — sdk.gen.ts, types.gen.ts, etc.). This is plumbing — drop it unless it surfaces a new user-visible field/flow.
- Real version gaps exist and are expected (e.g.
v1.3.2, v1.13.6, v1.20.0, the whole v1.24.x line were never tagged). Don't invent sections for them.
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"' package.json | head -1 # pending version
Compare the three. Common situations:
- Behind on tags — CHANGELOG missing released versions → backfill each gap (step 2 per gap).
[Unreleased] populated, package.json 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..origin/main for unreleased):
# 1. Tag date for the section header
git -c log.showSignature=false log -1 --format=%cs vB # YYYY-MM-DD
# 2. Commits in the range, first-parent (catches both merge commits AND squash merges)
git -c log.showSignature=false log vA..vB --first-parent --format='%h %s'
# 3. For each non-trivial PR, read its body for the user-facing description
gh pr view <number> --json title,body,labels
Group commits by prefix (feat:, fix:, refactor:, chore:, test:, docs:, ci:, style:) 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 -c log.showSignature=false show <sha> --stat # which files moved
git -c log.showSignature=false show <sha> -- <interesting-path>
git -c log.showSignature=false diff vA..vB -- src/routes/ # cumulative for an area
Verify the user-facing surface:
- New pages / routes → check
src/routes/ (and route groups (public), (auth)).
- New components / flows → check
src/lib/components/.
- i18n → check
messages/*.json / Paraglide sources (new languages, large string migrations).
- Settings/flags exposed in UI → check the relevant form components and
src/lib/api/ field additions.
- Auth/permissions → check
hooks.server.ts, guards, eligibility logic.
If the diff is purely internal (API-client regen, renames, helper extraction, type hints, test reorg, file-length splits, dependency bumps) and there is no observable change, drop it — even if the commit was feat:-prefixed.
4. Categorize
| Section |
Use for |
| Added |
New pages/routes, new user-facing components/features, new flows (RSVP, checkout, check-in), new i18n languages, new settings/toggles |
| Changed |
Behavior/UX changes to existing features, redesigns, copy changes with impact, performance visible to users |
| Fixed |
Bug fixes — describe the symptom the user saw |
| Deprecated |
Features still working but slated for removal |
| Removed |
Removed pages, features, options |
| Security |
Auth fixes, permission tightenings, XSS/sanitization, CSP fixes with user impact |
Bundle related commits into one bullet. A feature that spans several 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
- **Discount codes**: full admin CRUD under org admin — list page with search, status/type filters, and inline enable/disable; create/edit pages; scope assignment across series, events, and tiers.
- Image cropper modal when uploading a profile picture, letting you crop before saving.
### Fixed
- Tier prices no longer get corrupted on save under non-English browser locales (e.g. `33.33` becoming `33.31`).
- Returning users with "Remember Me" enabled are no longer shown as logged out after their access token expires.
Rules:
- Lead with the what, not the how.
- Backticks for code symbols (routes, component names, props, env vars).
- 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.
- The
## [0.x] — Initial development … summary stays pinned at the bottom; do not expand it into per-tag sections.
7. Verify
# Visual diff
git diff CHANGELOG.md
# Every released tag has exactly one section
for t in $(git tag | grep -E '^v1\.' | sed 's/^v//'); do
grep -qE "^## \[$t\] " CHANGELOG.md || echo "MISSING: $t"
done
# Section dates equal tag commit dates
grep -oE '^## \[1\.[0-9.]+\] - [0-9-]+' CHANGELOG.md | sed -E 's/## \[(.*)\] - (.*)/\1 \2/' | while read v d; do
td=$(git -c log.showSignature=false log -1 --format='%cs' "v$v" 2>/dev/null)
[ "$d" = "$td" ] || echo "MISMATCH $v: changelog=$d tag=$td"
done
Do 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.
- ❌ Relying on
--merges (misses squash-merged PRs) or trusting feat:/fix: prefixes without checking the diff.
- ❌ Forgetting
-c log.showSignature=false and drowning in GPG noise.
- ❌ Listing API-client regen, test additions, type fixes, file-length splits, or CI changes unless they affect users.
- ❌ 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
package.json or creating tags. Out of scope for this skill.
1---2name: update-changelog-23description: 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.4---56# Update Changelog78Maintains `CHANGELOG.md` (Keep a Changelog format, semver) by reconciling it against git tags, merged PRs, and actual code diffs.910## Format conventions (this repo)1112- Header: `## [X.Y.Z] - YYYY-MM-DD` for released versions, `## [Unreleased]` at the top.13- Section order: **Added**, **Changed**, **Fixed**, **Deprecated**, **Removed**, **Security**. Omit empty sections.14- Bullets describe **user-facing impact** (what an event organizer, attendee, or admin sees), not internal refactors. Drop pure CI/test/lint/type-fix commits unless they change observable behavior.15- Major features get a bold prefix: `- **Discount codes**: full admin CRUD…`. Optional nested sub-bullets for sub-features.16- Bug fixes name the symptom that was fixed, not the patch ("Tier prices no longer get corrupted on save under non-English browser locales").17- Backticks for code symbols: routes (`/org/[slug]/admin/financials`), component names, prop/flag names (`is_open_ended`, `max_tickets_per_user`), env vars (`PUBLIC_API_URL`).18- Dates are the **tag date** (committer date of the tag), not today's date.19- A version with no user-facing change still gets a header followed by:20 `_Maintenance release — internal, tooling, or dependency changes only._`2122## Release model (this repo)2324- The frontend mirrors the backend: `v`-prefixed semver tags, version in **`package.json`** (not `pyproject.toml`), released via `make release`.25- A "bump X.Y.Z" commit (often bundled with small fixes) lands on `main`, *then* the tag is pushed and the release created.26- **CHANGELOG.md should be updated in the same commit that bumps `package.json`** — write the new `## [X.Y.Z] - YYYY-MM-DD` section before the bump is merged.2728## ⚠️ Repo-specific gotchas2930- **Always pass `-c log.showSignature=false` to git** (e.g. `git -c log.showSignature=false log …`). Commits are GPG-signed and signature-verification noise otherwise floods every `git log`/`git show`.31- **Mixed merge styles.** Early history uses real merge commits; recent history uses **squash merges** with the PR number in the subject (`feat(x): … (#498)`). So gather commits with `--first-parent` on the full commit list — do **not** rely on `--merges` (it misses every squash merge).32- **API-client noise.** Most feature commits bundle a large regeneration of `src/lib/api/` (`pnpm generate:api` output — `sdk.gen.ts`, `types.gen.ts`, etc.). This is plumbing — drop it unless it surfaces a new user-visible field/flow.33- **Real version gaps exist** and are expected (e.g. `v1.3.2`, `v1.13.6`, `v1.20.0`, the whole `v1.24.x` line were never tagged). Don't invent sections for them.3435## Workflow3637### 1. Establish state3839```bash40git tag --sort=-v:refname | head -20 # latest tags41grep -E '^## \[' CHANGELOG.md | head -10 # versions present in changelog42grep '"version"' package.json | head -1 # pending version43```4445Compare the three. Common situations:4647- **Behind on tags** — CHANGELOG missing released versions → backfill each gap (step 2 per gap).48- **`[Unreleased]` populated, package.json bumped** — promote `[Unreleased]` to `## [X.Y.Z] - <tag-date>` and start a fresh empty `[Unreleased]`.49- **New work since last tag** — add entries to `[Unreleased]` only.5051### 2. Gather changes between two refs5253For each version gap `vA..vB` (or `vLast..origin/main` for unreleased):5455```bash56# 1. Tag date for the section header57git -c log.showSignature=false log -1 --format=%cs vB # YYYY-MM-DD5859# 2. Commits in the range, first-parent (catches both merge commits AND squash merges)60git -c log.showSignature=false log vA..vB --first-parent --format='%h %s'6162# 3. For each non-trivial PR, read its body for the user-facing description63gh pr view <number> --json title,body,labels64```6566Group commits by prefix (`feat:`, `fix:`, `refactor:`, `chore:`, `test:`, `docs:`, `ci:`, `style:`) as a first pass — but do not trust the prefix alone (see step 3).6768### 3. Verify impact from the diff6970A 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:7172```bash73git -c log.showSignature=false show <sha> --stat # which files moved74git -c log.showSignature=false show <sha> -- <interesting-path>75git -c log.showSignature=false diff vA..vB -- src/routes/ # cumulative for an area76```7778Verify the user-facing surface:7980- New pages / routes → check `src/routes/` (and route groups `(public)`, `(auth)`).81- New components / flows → check `src/lib/components/`.82- i18n → check `messages/*.json` / Paraglide sources (new languages, large string migrations).83- Settings/flags exposed in UI → check the relevant form components and `src/lib/api/` field additions.84- Auth/permissions → check `hooks.server.ts`, guards, eligibility logic.8586If the diff is purely internal (API-client regen, renames, helper extraction, type hints, test reorg, file-length splits, dependency bumps) and there is no observable change, **drop it** — even if the commit was `feat:`-prefixed.8788### 4. Categorize8990| Section | Use for |91|---------|---------|92| **Added** | New pages/routes, new user-facing components/features, new flows (RSVP, checkout, check-in), new i18n languages, new settings/toggles |93| **Changed** | Behavior/UX changes to existing features, redesigns, copy changes with impact, performance visible to users |94| **Fixed** | Bug fixes — describe the symptom the user saw |95| **Deprecated** | Features still working but slated for removal |96| **Removed** | Removed pages, features, options |97| **Security** | Auth fixes, permission tightenings, XSS/sanitization, CSP fixes with user impact |9899Bundle related commits into one bullet. A feature that spans several PRs becomes one bold-prefixed bullet, optionally with sub-bullets per sub-feature.100101### 5. Write entries102103Style examples lifted from this repo's existing entries — match the voice:104105```markdown106### Added107- **Discount codes**: full admin CRUD under org admin — list page with search, status/type filters, and inline enable/disable; create/edit pages; scope assignment across series, events, and tiers.108- Image cropper modal when uploading a profile picture, letting you crop before saving.109110### Fixed111- Tier prices no longer get corrupted on save under non-English browser locales (e.g. `33.33` becoming `33.31`).112- Returning users with "Remember Me" enabled are no longer shown as logged out after their access token expires.113```114115Rules:116117- Lead with the *what*, not the *how*.118- Backticks for code symbols (routes, component names, props, env vars).119- Bold prefix `**Name**:` only for headline features that warrant top-billing.120- One sentence per bullet; sub-bullets for multi-part features.121- No author/PR-number/issue-number references — those live in commit history and PRs.122123### 6. Insert into the file124125- `[Unreleased]` always stays at the top, even if empty (with no subsections), so future entries have a home.126- New released sections go directly under `[Unreleased]`, in descending version order.127- When promoting `[Unreleased]` to a version: copy the content under a new `## [X.Y.Z] - <tag-date>` heading and leave `[Unreleased]` empty.128- Preserve any existing `[Unreleased]` entries — they may already document work in the new version.129- The `## [0.x] — Initial development …` summary stays pinned at the bottom; do not expand it into per-tag sections.130131### 7. Verify132133```bash134# Visual diff135git diff CHANGELOG.md136137# Every released tag has exactly one section138for t in $(git tag | grep -E '^v1\.' | sed 's/^v//'); do139 grep -qE "^## \[$t\] " CHANGELOG.md || echo "MISSING: $t"140done141142# Section dates equal tag commit dates143grep -oE '^## \[1\.[0-9.]+\] - [0-9-]+' CHANGELOG.md | sed -E 's/## \[(.*)\] - (.*)/\1 \2/' | while read v d; do144 td=$(git -c log.showSignature=false log -1 --format='%cs' "v$v" 2>/dev/null)145 [ "$d" = "$td" ] || echo "MISMATCH $v: changelog=$d tag=$td"146done147```148149Do not run `make release` or push tags — the skill only edits `CHANGELOG.md`. The user runs `make release` themselves.150151## Anti-patterns152153- ❌ Dumping every commit subject as a bullet. Filter, group, rewrite.154- ❌ Using the date of editing as the section date — use the **tag's commit date**.155- ❌ Relying on `--merges` (misses squash-merged PRs) or trusting `feat:`/`fix:` prefixes without checking the diff.156- ❌ Forgetting `-c log.showSignature=false` and drowning in GPG noise.157- ❌ Listing API-client regen, test additions, type fixes, file-length splits, or CI changes unless they affect users.158- ❌ Inventing impact you can't confirm from the diff. If unsure, ask the user or omit.159- ❌ Overwriting existing `[Unreleased]` content when promoting it — merge, don't replace.160- ❌ Editing `package.json` or creating tags. Out of scope for this skill.