adding-changelog-entries

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:

1. Determine the changelog kind and body
2. Create the changelog entry YAML file in .changes/unreleased/
3. 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.