agentleFS
letsrevelletsrevel/revel-backend/.claude/skills/update-changelog/SKILL.md

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

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.
  • openchamberSkill

    clack-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

  • openchamberSkill

    drag-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

  • mitsuhikoSkill

    oebb-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

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
  1. Distinctive:

    Verify the user-facing surface:

    line 72
  2. Very specific:

    If the diff is purely internal (renames, helper extraction, type hints, test reorg) and there is no observable change, drop it — even if …

    line 80
  3. Very specific:

    No author/PR-number/issue-number references — those live in commit history and PRs.

    line 117
  4. Very specific:

    When promoting [Unreleased] to a version: copy the content under a new ## [X.Y.Z] - <tag-date> heading and leave [Unreleased] empty.

    line 123
  5. Very specific:

    Do not run make release or push tags — the skill only edits CHANGELOG.md.

    line 137

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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/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_url max 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 release runs gh release create v$VERSION --generate-notes using version from pyproject.toml.
  • A "bump X.Y.Z" PR (often bundled with small fixes — e.g. chore: bundled fixes (...) + bump 1.55.0) lands on main, then make release is invoked.
  • CHANGELOG.md must be updated in the same commit that bumps pyproject.toml — write the new ## [X.Y.Z] - YYYY-MM-DD section 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 version

Compare 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,labels

Group 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 subsystem

Verify the user-facing surface:

  • New endpoints / changed schemas → check events/controllers/, accounts/controllers/, */schema/, openapi.json if 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.py beat 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

SectionUse for
AddedNew features, new endpoints, new models, new settings/flags, new notification channels, new file format support
ChangedBehavior changes to existing features, API contract changes (non-breaking), default-value changes, performance changes visible to users
FixedBug fixes — describe the symptom
DeprecatedFeatures still working but slated for removal
RemovedRemoved features, endpoints, settings
SecurityAuth 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 events

Rules:

  • Lead with the what, not the how. ("Discord admin-ping channel" not "Added discord_admin_webhook_url setting and send_discord_admin_ping function").
  • 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.md

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.
  • ❌ 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.toml or creating tags. Out of scope for this skill.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.