Changelog Maintenance

The changelog records notable changes to the distributed software. Every entry must answer: "Does this change affect someone who uses, upgrades, deploys, or integrates with the project?" If not, omit it.

Format authority: Keep a Changelog 1.1.0 and Semantic Versioning 2.0.0.

Project constants

Detect the following constants from the project itself - do not ask the user unless detection fails. Inspect, in order: existing CHANGELOG.md entries, project documentation (README.md, CONTRIBUTING.md, docs/), and recent git commit messages.

1. GitHub repository slug (`OWNER/REPO`). Read existing comparison links at the bottom of CHANGELOG.md (preferred). Fall back to git remote get-url origin and parse the slug from the URL.
2. Issue tracker. Look for tracker references in existing CHANGELOG entries, PR templates, contributing docs, and recent commit messages:

• GitHub Issues - links of the form https://github.com/OWNER/REPO/issues/NNN, or closing keywords closes/fixes/resolves #NNN in commit/PR bodies.
• Jira - task keys of the form [A-Z]+-[0-9]+ (e.g. ABC-123) or links to *.atlassian.net/browse/....
• Linear - keys like ENG-123 or links to https://linear.app/....
• Other trackers - distinct ID schemes or links in commit/PR bodies.

For non-GitHub trackers, also detect the tracker base URL and the project key prefix (e.g. BP, ABC, ENG).

1. Subsystem labels. Read existing CHANGELOG entries to learn which subsystem prefixes the project already uses (e.g. API:, CLI:, Auth:). If none exist, propose labels that match the project's top-level directory or package layout. The human reviewer will correct any that are wrong.

Use the detected values everywhere a project key, tracker URL, or GitHub URL is needed. If a constant cannot be determined with confidence, ask the user once before proceeding. Do not guess or invent values.

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

CHANGELOG.md, if it exists, lives at the repository root. Read it first. If the file does not exist, create it from assets/changelog-template.md (see Step 5).

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 release window

# Last tag, its date (window start), and recent tags for context
LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null)
git log -1 --format="%ai" "$LAST_TAG"
git tag --sort=-version:refname | head -10

If no tags exist, treat the entire git history as the unreleased window. The release window is: tag date (exclusive) → today.

#### 2b: List merged PRs in the window

Primary: milestone-based (when the project sets milestones on PRs; replace MILESTONE_PREFIX with the prefix the project uses, e.g. M10):

gh pr list --state merged --limit 100 \
  --json number,title,mergedAt,milestone,labels \
  --jq '.[] | select(.milestone != null and (.milestone.title | startswith("MILESTONE_PREFIX")))
        | "\(.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

For non-GitHub trackers, also fetch resolved tasks within the same window using the tracker's search API or web UI - see references/trackers.md for the section matching the detected tracker.

#### 2c: Inspect individual PRs and link to tracker tasks

# 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 issue/task references from the PR body using the extraction commands in references/trackers.md for the tracker detected in Step 1. Read each linked issue/task for the user-facing problem statement: PR titles are implementation-focused, tracker items are user/operator-focused.

Use the PR body's Scope & Context section (when present) to understand the user-facing or operator-facing impact. 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 the project 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 a consumer of this project 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 consumer 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 consumer's perspective there was no intermediate broken state - only the delivered result.
• Fold sub-fixes into the feature entry. If a PR introduces a feature and also fixes a bug found during its implementation, describe the fix as part of the feature bullet. Only create a standalone Fixed entry when the PR's sole purpose is a bug fix that is independent of any in-progress feature.
• Reference the issue/task when one exists; fall back to the PR otherwise. Each bullet ends with a parenthetical reference using a full URL (plain #NNN or bare tracker keys are not clickable in rendered markdown). When a tracker issue/task is linked from the PR, reference the issue/task only - not also the PR. When multiple distinct issues/tasks are linked, list all of them. See references/trackers.md for the URL format matching the detected tracker.
• 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, using the labels detected in Step 1 (e.g. API:, CLI:, Auth:, Dashboard:).
• 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

Use assets/changelog-template.md as the structural template when creating CHANGELOG.md from scratch or adding the first versioned section. The template covers the preamble, [Unreleased] placeholder, a versioned section, and bottom comparison links.

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.
• [ ] Tracker references are full URLs, not bare keys or plain #NNN.
• [ ] When an issue/task exists, the bullet references the issue/task only - not also the PR.
• [ ] If the project's tracker is not GitHub Issues: no https://github.com/OWNER/REPO/issues/NNN links are present in the changelog.

Error Recovery

Anti-Patterns