Changelog Maintenance

Sortie's changelog speaks to operators and integrators who deploy and configure the service. Every entry must answer: "Does this change affect someone who installs, upgrades, configures, or integrates with Sortie?" If not, omit it.

Authoritative references:

• Keep a Changelog 1.1.0
• Common Changelog
• Semantic Versioning 2.0.0

When to use

• Adding entries for new features, fixes, or breaking changes.
• Preparing a release: moving Unreleased entries under a versioned heading.
• Creating CHANGELOG.md from scratch when it does not exist.

Workflow

Step 1: Read the current changelog

cat CHANGELOG.md

If the file does not exist, create it with the preamble from Step 4.

Step 2: Gather changes

The merged PR is the atomic unit of a changelog entry — not the commit. A single PR often contains the feature commit, follow-up fixes, review feedback, test additions, and docs updates. These are one logical change and produce one changelog bullet. Never split a PR's commits into separate entries.

2a: Identify the version boundary

# Find the last tag and its commit
git tag --sort=-version:refname | head -5
git log --oneline -1 "$(git describe --tags --abbrev=0 2>/dev/null)"

2b: Determine the release window and list merged PRs

First, find the date of the last tag — this is the start of the release window:

# Date of the last tag (use as the window start)
git log -1 --format="%ai" "$(git describe --tags --abbrev=0 2>/dev/null)"

Primary: milestone-based (when milestones are set):

# PRs in a specific milestone (e.g., M10)
gh pr list --state merged --limit 100 \
  --json number,title,mergedAt,milestone,labels \
  --jq '.[] | select(.milestone != null and (.milestone.title | startswith("M10")))
        | "\(.number)\t\(.mergedAt | split("T")[0])\t\(.title)"' \
  | sort -t$'\t' -k2

Fallback: date-based (when milestones are not set, replace YYYY-MM-DD with the tag date):

gh pr list --state merged --limit 200 \
  --json number,title,mergedAt,labels \
  --jq '.[] | select(.mergedAt >= "YYYY-MM-DDT00:00:00Z")
        | "\(.number)\t\(.mergedAt | split("T")[0])\t\(.title)"' \
  | sort -t$'\t' -k2

When preparing a new release, the window is: tag date (exclusive) → today.

2c: Inspect individual PRs when needed

# PR title, body (scope/intent), and constituent commits
gh pr view <NUMBER> --json title,body --jq '"\(.title)\n\(.body)"' | head -40
gh pr view <NUMBER> --json commits --jq '.commits[].messageHeadline'

# Extract linked issues from the PR body (all GitHub closing keywords, case-insensitive;
# handles optional markdown bold, optional colon, cross-repo owner/repo#N, multiple per line)
gh pr view <NUMBER> --json body --jq '.body' \
  | grep -ioE '\*{0,2}(close[ds]?|fix(e[ds])?|resolve[ds]?|related|part of)[^:#*]*:?\*{0,2}[[:space:]]+([A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+)?#[0-9]+'

Use the PR body's Scope & Context section to understand the user-facing impact. Note which issues the PR closes or references — these become part of the reference block in the changelog entry. Do not rely on git log --oneline — it shows commits, not logical changes.

If the user describes changes verbally, use that as the primary source.

Step 3: Filter — decide what belongs

The changelog records notable changes to the distributed software. A change is notable when it alters what a consumer of Sortie can observe: new capabilities, changed behavior, fixed bugs, security patches, removed features, or deprecation notices.

Apply the following filter to every commit or change before writing an entry.

ALWAYS include:

NEVER include — these are noise, not signal:

Edge cases — include only when the threshold is met:

When in doubt, ask: "If I were an operator reading this before upgrading, would I need to know this?" If the answer is no, leave it out.

Step 4: Classify each change

Place every surviving entry under exactly one category:

Writing rules:

• One bullet per logical change between releases. A logical change is everything the operator or integrator observes as a single unit of value. It may span multiple PRs and commits if they all deliver, refine, or fix the same capability within the release window.
• Fold within-release churn. If a feature is introduced in one PR and then corrected, polished, or adjusted in subsequent PRs before the release ships, all of that work produces one changelog entry describing the final state. From the operator's perspective there was no intermediate broken state — only the delivered result. Do not list each PR separately when they collectively form one observable change.
• Fold sub-fixes into the feature entry. If a PR introduces a feature and also fixes a bug discovered during its implementation (e.g., a race condition found while adding env overrides), describe the fix as part of the feature bullet — do not create a separate Fixed entry. Only create a standalone Fixed entry when a PR's sole purpose is a bug fix independent of any in-progress feature.
• Link every PR and issue parenthetically at the end of the bullet using full GitHub URLs — plain #NNN is not clickable in rendered markdown. Determine the repo URL from the comparison links at the bottom of CHANGELOG.md or via git remote get-url origin.
  • Issue: [#NNN](https://github.com/OWNER/REPO/issues/NNN)
  • PR: [#NNN](https://github.com/OWNER/REPO/pull/NNN)
  • When both an issue and its implementing PR are available, list both.
  • When multiple issues or PRs are explicitly linked, list all of them.
  • Multi-reference format — one reference per line inside the parens:
    Copy

    ([#398](https://github.com/OWNER/REPO/issues/398),
    [#403](https://github.com/OWNER/REPO/pull/403))
    

  • Single reference stays on the same line: ([#403](https://github.com/OWNER/REPO/pull/403)).
• Start each bullet with what changed, not with "Fixed" or "Added" (the heading already says that).
• Be specific: "coroutine 'main' was never awaited bug after async migration" not "Fixed async bug".
• Identify the subsystem when it helps locate the change: "Jira adapter:", "SQLite store:", "CLI:".
• Reference types or functions in backticks when they help the reader.
• Do not copy git commit messages verbatim — rewrite for a human reader.

Step 5: Write the entry

Format (Keep a Changelog 1.1.0):

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added

- Description of new capability.

## [X.Y.Z] - YYYY-MM-DD

### Fixed

- Description of what was broken and how it was fixed.

[Unreleased]: https://github.com/OWNER/REPO/compare/vX.Y.Z...HEAD
[X.Y.Z]: https://github.com/OWNER/REPO/compare/vA.B.C...vX.Y.Z

Structural rules:

• Reverse chronological order (newest first).
• [Unreleased] section always present at the top.
• Dates in ISO 8601 (YYYY-MM-DD).
• Comparison links at the bottom for every version.
• Empty categories are omitted (no ### Removed if nothing was removed).

Step 6: Determine the version bump

When cutting a release, choose the version number:

To cut a release:

1. Replace ## [Unreleased] with ## [X.Y.Z] - YYYY-MM-DD.
2. Add a fresh empty ## [Unreleased] section above it.
3. Update the comparison links at the bottom.

Step 7: Verify

• Every entry passes the filter from Step 3 (no noise).
• Newest version is at the top.
• Every version has a date (except Unreleased).
• Bottom links are correct and complete.
• No empty category headings.
• No git-log copy-paste — entries are human-readable.
• Entries identify the subsystem where helpful.

Error Recovery

Anti-Patterns