| name | adding-changelog-entries |
| description | Use when you need to add a changelog entry for a code change. Invoke after making code changes that warrant a changelog entry, or when the user asks to add a changelog entry. |
*CRITICAL* Add the following steps to your Todo list using TodoWrite:
- Determine the changelog kind and body
- Create the changelog entry YAML file in
.changes/unreleased/
- Verify the entry was created correctly
Overview
This project uses changie to manage changelog entries. Each change gets a YAML file in .changes/unreleased/ that is later batched into CHANGELOG.md during releases.
Step-by-step
1. Determine the changelog kind and body
Select the appropriate kind based on the change:
| Kind | When to use | Version bump |
|---|
| Added | New features or capabilities | minor |
| Changed | Changes to existing functionality | patch |
| Deprecated | Features marked for future removal | patch |
| Fixed | Bug fixes | patch |
| Performance | Performance improvements | patch |
| Removed | Removed features or capabilities | patch |
| Reverted | Reverted previous changes | patch |
| Dependencies | Dependency updates | patch |
| Security | Security-related fixes | patch |
The body must have at least 1 character. The first line of the body is used as the title in the rendered changelog. Additional lines provide details.
If the kind or body is ambiguous, ask the user for clarification.
2. Create the changelog entry YAML file
Create the file directly — do not run changie new interactively.
File location: .changes/unreleased/<unique-name>.yaml
File naming: Use a timestamp-based name to avoid collisions. Generate it using:
date -u +"%Y%m%dT%H%M%S"
Then name the file .changes/unreleased/<timestamp>.yaml.
File format:
kind: <Kind>
body: |-
First line is the title
Optional additional details go here.
Multi-line bodies are supported.
time: <ISO 8601 timestamp>
Generate the ISO 8601 timestamp using:
date -u +"%Y-%m-%dT%H:%M:%S.%NZ"
Example entry (.changes/unreleased/20260328T043000.yaml):
kind: Added
body: |-
Add `batch_insert` function to `mesa/set`
Allows inserting multiple key-value pairs in a single call,
reducing round-trips to Mnesia.
time: 2026-03-28T04:30:00.000000000Z
3. Verify the entry
After creating the file, verify it:
- Confirm the file exists in
.changes/unreleased/
- Confirm the YAML is valid (kind is one of the 9 allowed values, body is non-empty, time is present)
Important notes
- One entry per logical change. If a PR has multiple distinct changes, create multiple entries.
- Do not modify existing entries in
.changes/unreleased/ unless explicitly asked.
- Do not run
changie batch or changie merge — those are release-time operations.
- CI checks for the presence of a
.changes/unreleased/ entry on PRs.
