Log Changes

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  --json title,body --jq '"\(.title)\n\(.body)"' | head -40
gh pr view  --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:

| Signal | Why it matters to consumers | | ------------------------------------------------------------------------------------------ | ------------------------------------- | | New user-facing feature (CLI flag, integration, config option, API surface, UI capability) | Consumers discover new capabilities | | Changed behavior of existing feature | Consumers must adjust usage | | Bug fix for incorrect behavior | Consumers know issues are resolved | | Security or vulnerability fix | Operators must act on upgrades | | Deprecation of public interface | Consumers prepare for removal | | Removal of feature or public interface | Consumers must adapt before upgrading | | Performance improvement with measurable impact | Consumers benefit from upgrading | | New or changed persistence schema (migration) | Operators plan upgrade procedures | | Changed CLI flags, env vars, deployment, or config file format | Operators must update deployment config |

NEVER include - these are noise, not signal:

| Noise | Why it does not belong | | --------------------------------------------------------- | ------------------------------------- | | Internal variable/function/type renames | No observable effect on consumers | | Code formatting, whitespace, linting fixes | No observable effect on consumers | | Test-only changes (new tests, test refactors) | Not shipped to consumers | | CI/CD pipeline changes (workflows, actions) | Not shipped to consumers | | Dotfile changes (.gitignore, .github/*, CODEOWNERS) | Not shipped to consumers | | Documentation-only changes (README, CLAUDE.md, AGENTS.md, comments) | Not shipped to consumers | | Merge commits | Infrastructure artifact, not a change | | Internal refactoring with no behavior change | No observable effect on consumers | | Dev-only dependency bumps | Not shipped to consumers | | Project scaffolding and repo housekeeping | Not shipped to consumers |

Edge cases - include only when the threshold is met:

| Change | Include when... | Omit when... | | ------------------------------ | ---------------------------------------------------------------- | --------------------------------------- | | Dependency bump | Major version, security fix, or changed behavior | Routine patch/minor with no user impact | | Refactoring | It changes observable performance, error messages, or log output | Purely internal restructuring | | New internal module/package | It introduces a new adapter or public API surface | It reorganizes existing code | | ADR or architecture doc update | It records a decision that changes system behavior | It clarifies existing behavior |

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:

| Category | When to use | | -------------- | ---------------------------------------------------------------------------- | | Added | New user-facing capability: CLI command, integration, config option, API surface, UI capability | | Changed | Existing behavior altered in a way consumers can observe | | Deprecated | Still works but scheduled for removal in a future version | | Removed | Previously available feature or interface deleted | | Fixed | Bug fix - incorrect behavior corrected | | Security | Vulnerability patch, dependency CVE fix |

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:

| Bump | Trigger | | --------- | ----------------------------------------------------- | | Major | Breaking API/CLI change for users or operators, removed public functionality | | Minor | New feature, backward-compatible behavior change | | Patch | Bug fix, security patch |

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

| Problem | Fix | | -------------------------- | ---------------------------------------------------------- | | Missing comparison links | Reconstruct from git tag --sort=-version:refname | | Duplicate entries | Deduplicate, keep the more descriptive version | | Entry under wrong category | Move it; if ambiguous, prefer Changed over Added | | No tags in repository | Use commit SHAs in comparison links as a temporary measure | | Noise entry slipped in | Remove it - a leaner changelog is more trustworthy |

Anti-Patterns

| Anti-pattern | Why it's wrong | Correct approach | | --- | --- | --- | | One entry per commit | Commits are implementation steps, not logical changes. A 6-commit PR produces one changelog bullet. | Use gh pr list to enumerate PRs; write one bullet per logical change. | | Using git log --oneline as the primary source | Produces commit-level noise: test commits, review feedback, merge commits, formatting fixes. | Query merged PRs via gh pr list --state merged filtered by milestone or date range since the last git tag. | | Plain #NNN references | Not clickable in rendered markdown - readers must manually construct the URL to navigate to the change. | Use full URLs (see references/trackers.md). | | Including both the issue/task and the PR in one bullet | Doubles the noise and misleads the reader: the issue/task already describes the user-visible problem, the PR is its implementation. | Reference the issue/task only when one exists; fall back to the PR only when no issue/task is available. | | Bare tracker keys (e.g. BP-123, ENG-42) | Not clickable; readers cannot navigate to the task without knowing the tracker URL. | Use the full tracker URL (see references/trackers.md). | | GitHub Issue links in changelog when the project's tracker is not GitHub Issues | The detected tracker is the authoritative source for task references. Adding /issues/NNN links is misleading and breaks over time as the GitHub Issues ta

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sergeyklay
• Source: sergeyklay/.agents
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.