Changelog examples with annotated entries and noisy ones rewritten

A changelog is the file a developer opens when they're about to bump a dependency and want to know what will break. It isn't marketing and it isn't a dump of your git log. It's a curated, dated history of notable changes to the project, kept in the repo next to the code.

Below are changelog examples in the Keep a Changelog style, with notes on why each part is there, followed by noisy entries rewritten into ones a maintainer can scan.

A minimal file that works

# Changelog

All notable changes to this project are documented in this file.

The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.

## [Unreleased]

### Added
- `--dry-run` flag for `sync` that prints planned writes without applying them.

## [2.4.0] - 2026-10-12

### Added
- `retry.maxDelay` option to cap exponential backoff.

### Changed
- `connect()` now times out after 30s by default, up from 10s.

### Deprecated
- `client.legacyAuth()`. Use `client.auth({ mode: "token" })` instead.
  Scheduled for removal in 3.0.0.

### Fixed
- Memory leak when a stream was closed before the first chunk. #812

## [2.3.1] - 2026-09-03

### Security
- Reject redirects to non-HTTPS hosts when `strictTls` is set. CVE-2026-0000

[Unreleased]: ../../compare/v2.4.0...HEAD
[2.4.0]: ../../compare/v2.3.1...v2.4.0
[2.3.1]: ../../compare/v2.3.0...v2.3.1

Annotations, part by part

The header lines. Two sentences tell a reader what the file promises. Saying you follow semantic versioning sets expectations. A minor bump shouldn't break their build.

Unreleased at the top. Changes land here as they merge. On release day you rename the heading to the version and date. Nobody has to dig through commits the night before.

Newest version first. People open the file to see what changed lately, so the latest release sits on top.

ISO dates. 2026-10-12 sorts cleanly and reads the same in every country.

The six change types. Added, Changed, Deprecated, Removed, Fixed and Security. Grouping by type lets someone jump straight to the part that affects them. A reader who only cares about breaking changes reads Changed and Removed and moves on.

Code formatting for names. Flags, options and functions are in backticks, so they're searchable and copyable.

Old and new values. "30s by default, up from 10s" saves a trip to the diff.

A migration path on deprecations. Every deprecation names the replacement and the version where the old thing goes away.

Compare links at the bottom. Each version heading links to a diff between tags. The changelog stays short, and the full detail is one click away.

Noisy entries, rewritten

Most bad changelogs come from pasting commit subjects straight in. Here's what that tends to look like.

## 2.4.0

- Merge pull request #799 from dev/feature-branch
- fix
- Updated deps
- refactor client
- WIP retry stuff
- Fixed the thing Sam reported
- bump version

Every line here is true and almost none of it helps. Merge commits, version bumps and refactors with no visible effect don't belong. "The thing Sam reported" means nothing outside your team chat. Here's the same release, cleaned up.

## [2.4.0] - 2026-10-12

### Added
- `retry.maxDelay` option to cap exponential backoff. #799

### Changed
- Bump `undici` to 6.x. Node 18 is now the minimum version.

### Fixed
- `parse()` no longer throws on empty response bodies. #805

Seven lines became three, and each one tells a reader whether they need to act. The dependency bump stayed because it changes the supported Node range. That's the only reason a reader would care about it.

One more before and after

- Changed how config loading works to be more flexible and also fixed
  some edge cases around env vars that could cause issues in some setups

### Changed
- Config files are now merged in order. Later files override earlier ones.

### Fixed
- Empty env vars no longer override values set in a config file. #788

The original mixed a behavior change and a bug fix in one long sentence. Splitting them puts each under the right heading. It also makes the breaking part easy to spot.

Habits that keep the file useful

• Update CHANGELOG.md in the same pull request as the change. A CI check that fails when src/ changes without a changelog edit works well on busy repos.
• Write each line for someone who hasn't read the code.
• Mark breaking changes clearly, at the start of the line, with BREAKING.
• Link the issue or PR number at the end, not in place of a description.
• If you generate the file from conventional commits, still read it before you tag. Generated entries often need a human edit.

If your entries run long, a short post on shorter writing that keeps the meaning covers ways to trim a line without losing the detail. When a whole release section feels wordy, Rephrase AI can reword it with its Professional profile, and a quick diff against your draft shows whether any version number or flag name went missing. A tight changelog makes every upgrade an easier call.