Release notes

Read-only. Reads git history and writes a document to stdout. Never tags, never pushes, never touches a remote.

Inputs

• base — what is already out. Defaults to the latest tag reachable from HEAD.
• head — what is going out. Defaults to the current branch.

Steps

1. Resolve the range:

   git fetch --tags --quiet
   BASE="${base:-$(git describe --tags --abbrev=0)}"
   git log --no-merges --pretty='%h%x09%an%x09%s' "$BASE..${head:-HEAD}"

2. For any commit whose subject does not say what changed for a user, read the diff before writing about it:

   git show --stat <sha>

   "fix stuff" and "PR feedback" are the two that always need this.

3. Group by what a reader can now do differently, not by commit type. A reader does not care that four commits were refactor. They care whether the export is faster.

4. Flag anything that needs a human before deploy: migrations, config keys, feature flags, changed queue names, breaking API changes.

   git diff --name-only "$BASE..HEAD" | grep -Ei 'migration|liquibase|flyway|\.env|values.*\.ya?ml'

Output

## <version> — <date>

<One sentence: what this release is for. If you cannot write it, the release
has no theme, and saying that is useful information.>

### Changes
- <what a user can now do, with the ticket reference>

### Needs attention before deploy
- <migration, config key, flag — or "nothing" if genuinely nothing>

### Internal
- <refactors, dependency bumps, CI — the part nobody reads, kept short>

Rules

• Never invent a ticket reference. If a commit has none, say so.
• Nothing under "Needs attention" without a file path proving it.
• An empty range means no release. Say that instead of writing a document.