Skip to content

CHANGELOG policy

Plan 113 WI-5 — keep CHANGELOG.md honest and useful by tying every user-visible change to a [Unreleased] entry at PR merge time.

When to update CHANGELOG.md

MUST update for:

  • New endpoints, routes, frontend features that customers can see
  • Bug fixes that change observable behaviour
  • Performance improvements that customers will notice (latency, page load times, etc.)
  • Breaking changes to public APIs, request/response schemas, or configuration formats
  • Security fixes (mark with [Security] prefix per the Keep-A-Changelog convention)

Exempt from updating:

  • Pure refactors that don't change behaviour (extracting a helper, consolidating duplicates)
  • Test-only changes
  • Documentation-only changes
  • CI / pre-commit hook tweaks
  • Internal-tool changes that don't ship to production

If you're unsure, default to writing an entry — over-documentation is cheap; missing entries hurt customer-facing release notes.

Format

Follow Keep-A-Changelog — group entries under [Unreleased] by category:

## [Unreleased]

### Added
- New endpoint `GET /tenant/whatever` returning ...

### Changed
- Plan 113 — consolidated cache facade under `rekognise.shared.cache`

### Fixed
- Plan 113 — auth uniformization: `_require_org_admin` delegations no
  longer drift across routers

### Security
- ...

### Deprecated
- ...

### Removed
- ...

Each entry should:

  • Lead with the plan number when applicable (Plan 113 — …)
  • Use one-line summaries; link to the PR / commit for detail
  • Use past tense for fixes / changes, present for additions

Enforcement

Pre-commit hook

A pre-commit hook (changelog-reminder in .pre-commit-config.yaml) warns when a commit touches code outside docs/, tests/, and the build / config infrastructure WITHOUT also touching CHANGELOG.md. The hook is warning-only (does not block the commit) because:

  • Trivial fixes (typos, comment updates) don't need an entry, and a blocking hook adds friction with no value.
  • Multi-commit branches often touch CHANGELOG in a separate commit at the end.

If the warning fires and you intend NOT to update the changelog, acknowledge it explicitly in the PR description ("internal-only, no user-visible behaviour").

PR template

.github/PULL_REQUEST_TEMPLATE.md carries a CHANGELOG checkbox. PR reviewers should not approve a PR that ships user-visible behaviour without a checked box (or an explicit no-entry rationale).

Release process

Before tagging a release, the engineering lead rewrites [Unreleased] to [<version>] - <YYYY-MM-DD> and starts a fresh [Unreleased] heading. Any post-release fix lands under the new [Unreleased].

History

  • v0.11.x sprint (2026-03 → 2026-05) — multiple PRs landed without CHANGELOG updates because there was no enforcement. This caused the v0.11.46 release notes to drift from reality.
  • Plan 113 WI-5 — installed pre-commit warning + PR template + this policy.