SpunkArt
Command line and project setup

How to keep a changelog people actually read

A changelog is a file that tells users what changed between versions of a project and whether an upgrade is safe. It is written for people, not machines, which is why a raw list of commit messages is a poor substitute.

Changelog versus commit log

Commits record how the code changed, step by step, for developers. A changelog records what that means for someone who uses the software. Ten commits that rename variables, fix typos and tune a test may add up to a single line: “Fixed: export no longer drops the last row.” Some commits never appear at all, and one feature built over weeks becomes one entry.

A widely used format

Many projects follow the convention published as “Keep a Changelog”. The file is called CHANGELOG.md, newest version at the top, and each release groups its entries under fixed headings:

HeadingUse it for
AddedNew features
ChangedChanges to existing behaviour
DeprecatedFeatures that still work but will be removed
RemovedFeatures that are now gone
FixedBug fixes
SecurityFixes for vulnerabilities

Leave out headings that have no entries in a release. Fixed headings let a reader skip straight to the part they care about, and someone scanning for risk can read Changed, Removed and Security only.

A sample file

# Changelog

## [Unreleased]
### Added
- CSV export can include a header row (`--header`).

## [2.0.0] - YYYY-MM-DD
### Changed
- **Breaking:** `--out` now expects a folder, not a file name.
  Rename `--out report.csv` to `--out reports/`.
### Removed
- The `legacy` output format, deprecated in 1.6.0.

## [1.6.1] - YYYY-MM-DD
### Fixed
- Export no longer drops the last row when the input
  has no trailing newline.

Write the release date in ISO form, year then month then day, which sorts correctly and reads the same in every country. The Unreleased section at the top collects entries as you merge work, so release day is a matter of renaming that heading.

How the version number follows the changelog

With semantic versioning, the entries tell you which number to raise:

  1. Anything under Removed, or a Changed entry that breaks existing use, means a new major version: 1.6.1 becomes 2.0.0.
  2. Added or Deprecated entries with nothing breaking mean a new minor version: 1.6.1 becomes 1.7.0.
  3. Only Fixed or Security entries mean a new patch: 1.6.1 becomes 1.6.2.

When the major or minor number goes up, the lower numbers reset to zero.

Writing good entries

  • Describe the effect, not the code. “Search now ignores accents” beats “Refactor normaliser”.
  • Mark breaking changes loudly and include the migration step in the same entry.
  • Link the issue or pull request when one exists, so curious readers can see the discussion.
  • Credit outside contributors by handle if your project does that; it is a kind thank-you.
  • Be honest about security fixes. Say a vulnerability was fixed and that users should upgrade, even if details wait until people have had time to update.

Generating a draft from commits

If the team writes commit messages in a structured style such as Conventional Commits (feat:, fix:, feat!: for breaking), release tools can sort commits into a draft. Treat the result as a first draft. Read it, merge duplicates, delete internal noise and rewrite entries in the reader’s language. To list what changed since the last tag by hand:

git log --oneline v1.6.1..HEAD

Common mistakes

  • Dumping the full commit log into the file.
  • Hiding a breaking change in a list of fixes.
  • Forgetting the file for a few releases, which leaves a gap that is hard to fill later.
  • Editing old entries after release. Add a correction to a new entry instead.

Questions

Do GitHub release notes replace a changelog?

They can, but a file in the repository travels with the code, works offline and survives a move to another host.

Should internal-only projects keep one?

If other teams depend on them, yes. They are users too.