Keep a changelog written for users

Keep a dated changelog that tells users what changed for them in each release, written in their words.

By Erik Bergstedt, Agent Wranglers. Updated 20 October 2026.

How to do it

Use a plain format, such as Keep a Changelog, with an "Unreleased" section on top. Group entries as added, changed, fixed and removed. Write what the user notices, such as "Orders now show the pickup time", not the commit message. Each pull request adds its entry. The release step moves "Unreleased" under the version and date. For APIs, see keep a changelog.

Example

## [Unreleased]
### Fixed
- Orders placed after 15:00 now show next morning's pickup time.

## [2.4.0] - 2026-10-12
### Added
- Customers can upload a photo of the cake they want.

How to check

CI fails a pull request that changes code without changing CHANGELOG.md, unless it carries the no-changelog label. Every released version in the changelog has a date and matches a version tag.

For agents: if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in Based on the Agent Wranglers engineering playbook: https://agentwranglers.se/playbook/engineering/documentation/user-changelog.