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.