Changelog Template for Software Teams

The template

This follows the Keep a Changelog conventions, which are the closest thing to a standard in this area and which most developers will already recognise.

# Changelog

All notable changes to this project are documented here.

The format is based on [Keep a Changelog](https://keepachangelog.com),
and this project adheres to [Semantic Versioning](https://semver.org).

## [Unreleased]

### Added
- Bulk archive for completed items

## [2.4.0] - 2026-09-20

### Added
- Recurring appointments with weekly, fortnightly and monthly repeats

### Changed
- CSV export now streams; accounts above 20,000 rows no longer time out

### Deprecated
- `/v1/appointments` returning Unix timestamps. Use ISO 8601 via the
  `Accept-Version: 2` header. Removal planned for 3.0.0

### Fixed
- Appointment reminders showed the wrong time for users in UTC+13
- Deleted clients remained visible in the calendar

### Security
- Session tokens now rotate on password change (CVE-2026-XXXXX)

## [2.3.1] - 2026-09-02

### Fixed
- Search returned no results for queries containing an apostrophe

[Unreleased]: https://github.com/you/project/compare/v2.4.0...HEAD
[2.4.0]: https://github.com/you/project/compare/v2.3.1...v2.4.0
[2.3.1]: https://github.com/you/project/compare/v2.3.0...v2.3.1

The six categories

Keep a Changelog defines six, and the value of using exactly these is that readers do not have to learn your taxonomy.

• Added - new features.
• Changed - changes to existing behaviour. This is where most breaking changes live, so say clearly when one is breaking.
• Deprecated - features that still work but are going away. Always give the removal version or date; a deprecation without one is ignored.
• Removed - features that are gone. Anything here was in Deprecated at least one release earlier, or you have broken someone without warning.
• Fixed - bug fixes, described as the symptom the user saw.
• Security - vulnerabilities addressed. Separate from Fixed because it is the one section people scan for, and it drives upgrade urgency.

Omit any category with no entries. Do not invent new ones; "Miscellaneous" is where changelogs go to die.

The conventions worth keeping

Newest at the top. Nobody scrolls to the bottom of a changelog to find out what changed last week.

An Unreleased section. Entries go here as work merges, not at release time. This is the single habit that determines whether your changelog is accurate, because the alternative is reconstructing it from a Git log under time pressure.

ISO dates. 2026-09-20, not 20/09/2026, which means different things in different countries.

Compare links at the bottom. The diff between two versions is what a developer actually wants when the description is not enough. Cheap to add, disproportionately useful.

Write for humans. A changelog generated directly from commit messages is a Git log with extra steps, and the whole point of the document is that it is not that.

How versioning interacts with this

Under semantic versioning, the categories map onto the version bump:

• Anything in Removed, or a breaking entry in Changed, forces a major bump.
• Added or Deprecated entries mean at least a minor bump.
• Only Fixed and Security means a patch.

Which gives you a useful check that runs in the other direction: write the changelog entries first, then read off the version number. If someone proposed a patch release and there is an entry in Removed, one of the two is wrong.

If you ship a web app rather than a library, semantic versioning carries less meaning and dated entries without version numbers are a legitimate choice. Keep the categories either way.

Changelog or release notes?

Different documents for different readers. The changelog is complete and chronological, written for developers, support staff and your future self. Release notes are selective and written for users, and a release note listing every entry has failed.

A small team can maintain one document and usually should, but be clear which one you are writing. The failure mode is a document that is too incomplete to debug from and too detailed to read. See the release notes template.

Generating it instead of writing it

Every changelog dies the same way: the Unreleased section stops being updated, three releases go out without entries, and reconstructing them becomes a job nobody will do.

There are two durable fixes. Either enforce it in review, so a pull request that changes behaviour without a changelog entry does not merge, or generate it from the work items in a release so there is no separate document to keep in sync.

FlowBoard takes the second approach: a release is a set of work items, and the changelog is generated from them, so the entry is written when the work is done by the person who did it rather than at release time by whoever is free.

Either way the principle is the same: capture at the moment of the change, not at the moment of the release. See release notes strategy.