From d7bd710ca275a8458833faf7eb18a549298f9494 Mon Sep 17 00:00:00 2001
From: Petr Simecek <petr@keboola.com>
Date: Sun, 26 Apr 2026 01:10:32 +0200
Subject: [PATCH] docs(claude): non-negotiable CHANGELOG.md update rule +
 [Unreleased] skeleton (#59)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CLAUDE.md gains a "Changelog discipline — non-negotiable" section above
"Git Commits & Pull Requests". Codifies the rule that every PR touching
user-visible behavior must update CHANGELOG.md under [Unreleased] in
the same PR — with concrete instructions for which sections to use,
how to mark breaking changes, and what counts as user-visible.

CHANGELOG.md gets an [Unreleased] skeleton above [0.11.0] so the next
PR has somewhere obvious to land its bullet, plus the inaugural
[Unreleased] entry documenting this very rule (eats its own dog food).

The rule is intentionally strict ("no exceptions, no follow-ups") —
soft "should" rules erode under pressure; binding rules survive PR
churn. Reviewers should bounce PRs that violate it, same as they'd
bounce a PR with no test changes for new logic.
---
 CHANGELOG.md |  9 +++++++++
 CLAUDE.md    | 19 +++++++++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 572751d..29d19b8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,15 @@ CalVer image tags (`stable-YYYY.MM.N`, `dev-YYYY.MM.N`) are produced for every C
 
 ---
 
+## [Unreleased]
+
+<!-- Add bullets here. Group: Added / Changed / Fixed / Removed / Internal.
+     Mark breaking changes with **BREAKING** at the start of the bullet. -->
+
+### Internal
+
+- `CLAUDE.md` — non-negotiable changelog discipline: every PR touching user-visible behavior must update `CHANGELOG.md` under `## [Unreleased]` in the same PR.
+
 ## [0.11.0] — 2026-04-26
 
 First tagged semver release. The `version = "2.x"` strings that appeared in earlier `pyproject.toml` snapshots were arbitrary placeholders from the initial scaffold and never reflected actual API maturity — resetting to pre-1.0 to signal that things may still shift.
diff --git a/CLAUDE.md b/CLAUDE.md
index af03a16..8343c9d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -272,6 +272,25 @@ When you motivate a change, frame it abstractly ("behind a TLS-terminating rever
 
 Customer-specific automation, hostnames, and identities live in private infra repos that *consume* this OSS. The OSS describes capabilities, defaults, and configuration knobs — not how a specific operator wired them up.
 
+## Changelog discipline — non-negotiable
+
+**Every PR that adds, removes, or changes user-visible behavior MUST update `CHANGELOG.md` in the same PR.** No exceptions, no follow-ups, no "I'll do it after merge". User-visible = anything an operator, end-user, or downstream integrator can observe: CLI flags / output / exit codes, REST endpoints / payloads / status codes, web UI, `instance.yaml` schema, env vars, `extract.duckdb` contract, Docker / compose / Caddyfile knobs, default behaviors, breaking changes, security fixes.
+
+**How:**
+- Add a bullet under the topmost `## [Unreleased]` heading (create one if missing — it sits above the latest released version).
+- Group by `### Added` / `### Changed` / `### Fixed` / `### Removed` / `### Internal` (Keep-a-Changelog sections).
+- Mark breaking changes with `**BREAKING**` at the start of the bullet — operators grep for that string before bumping the pin.
+- Reference the relevant doc/runbook if one exists (e.g. `see docs/auth-groups.md`), don't restate it.
+- Internal-only changes (refactors, test additions, dependency bumps without behavior change) go under `### Internal` — still log them, just keep them terse.
+
+**When you cut a release:**
+- Rename `## [Unreleased]` → `## [X.Y.Z] — YYYY-MM-DD`.
+- Append a new empty `## [Unreleased]` section at the top so the next PR has somewhere to land.
+- Bump `version` in `pyproject.toml` to match `X.Y.Z`.
+- Tag the merge commit as `vX.Y.Z` and push the tag.
+
+**If you find yourself opening a PR without a CHANGELOG entry, stop and add one before requesting review.** Reviewers should bounce PRs that touch user-visible behavior without a changelog update — same way they'd bounce a PR with no test changes for new logic.
+
 ## Git Commits & Pull Requests
 
 - Keep commit messages clean and concise