| name | changelog-update |
| description | Coalesce commits since the last git tag into a ChangeLog entry following the project's strict rules (4 sections, terse, no commit IDs, no trivial fixes). Use when the user says "update the ChangeLog" or as a step of /version-bump. |
ChangeLog update
The ChangeLog file lives at repo root. Per CLAUDE.md, it has very specific rules — they exist because the ChangeLog targets emulator users, not developers, and is NOT an exhaustive change log.
Inputs
- Target version: the version that will be bumped to (e.g.
v0.92.0). If unknown / not bumping, use (current date) per CLAUDE.md fallback.
- Date: today's date in
YYYY-MM-DD form.
Source material
git log --oneline <last-tag>..HEAD
git log --stat <last-tag>..HEAD
Also scan handover memos since the last tag for "what this session did" sections — they're often more readable than raw commit messages.
The 4 sections (in this order)
For each commit, classify into exactly ONE section. Drop trivial commits entirely.
User Features
New things the user (= someone running games / programs) will notice. Examples:
- New GUI screen / menu item
- New emulation feature (e.g. "MMU memory contention now modelled")
- New main-menu option
- Significant performance improvement
Developer Features
New things a developer using jnext will notice. Examples:
- New debugger feature
- New instrospection panel
- New CLI flag
- New test framework capability
Bug Fixes
Functional fixes that change behaviour for the user. Examples:
- "NextZXOS now boots past the supervisor screen"
- "Audio no longer crackles on Beast"
Internal JNEXT Development
Big architectural/test/process changes the user doesn't directly see but that are worth noting. Examples:
- "Subsystem audit framework with enumeration-table mandate"
- "Regression test suite restructured to 33 screenshot cases"
Style rules (strict)
- One line per entry, 10–20 words. No exceptions.
- Coalesce similar items. If 5 commits all touch DMA timing, that's ONE entry.
- NO commit IDs. Don't paste SHAs.
- NO trivial fixes. Reformats, doc tweaks, test name changes, internal renames, project-plan updates, CI tweaks — drop entirely.
- NO ongoing features. If a feature is half-done or has known bugs, do NOT include it. Per CLAUDE.md: "Don't be overly confident about features."
- Most recent at top. Reverse chronological.
File format
# ChangeLog
## vX.Y.Z (YYYY-MM-DD)
### User Features
- ...
### Developer Features
- ...
### Bug Fixes
- ...
### Internal JNEXT Development
- ...
## vP.Q.R (date)
...
If no commits exist for a section, omit the section (don't leave an empty header).
Workflow
- Find last tag:
git describe --tags --abbrev=0.
- Get commit list:
git log --oneline <last-tag>..HEAD.
- For each commit, ask: "would an end-user / developer-user / triager care about this in a changelog?" If no → drop.
- Classify the rest into the 4 sections.
- Coalesce similar items into single 10–20 word lines.
- Write the new entry at the top of
ChangeLog (above the previous version's entry).
- Show the diff to the user. Do NOT commit until they confirm — per CLAUDE.md, ChangeLog updates are user-requested.
Hard rules
- CLAUDE.md says: "The file should only be updated when the user requests it." Don't pre-empt.
- Don't push. Commit locally only.
- Don't include "Co-Authored-By" in the ChangeLog commit message (CLAUDE.md project mandate).
- Don't claim work that isn't tested. If a fix didn't pass the triplet, leave it out.
