---
title: "Keep a changelog written for users · Agent Wranglers"
url: https://agentwranglers.se/playbook/engineering/documentation/user-changelog
updated: 2026-10-20
licence: "All rights reserved"
---

# Keep a changelog written for users

By Erik Bergstedt, Agent Wranglers. Updated 2026-10-20.

- Level: Recommended
- Chapter: [Documentation](https://agentwranglers.se/playbook/engineering/documentation)
- Rule: Keep a dated changelog that tells users what changed for them in each release, written in their words.
- How: 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](https://agentwranglers.se/playbook/api-design/changes-over-time/api-changelog).
- 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.

Example:

```markdown
## [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.
```

**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`.

- Previous: [Generate reference docs from the code](https://agentwranglers.se/playbook/engineering/documentation/generated-reference)
- Next: [Test the docs in the build](https://agentwranglers.se/playbook/engineering/documentation/tested-docs)
- [Documentation](https://agentwranglers.se/playbook/engineering/documentation)