changelog-review

Changelog Review

This skill audits, creates, and maintains changelogs in Python projects following the Keep a Changelog 1.1.0 format and Semantic Versioning 2.0.0.

Before you start

Read the best-practices reference file to ground your review:

cat references/best-practices.md

Use the rules and source citations in that file as your authoritative checklist.

Modes of operation

This skill operates in one of four modes depending on what the user needs. Determine the mode from their request, then follow the corresponding workflow.

---

Mode 1 — Audit an existing changelog

Use when the user says things like "review my changelog", "is my changelog correct", or "check my CHANGELOG.md".

Step 1: Read the changelog

Open CHANGELOG.md (or HISTORY.md, NEWS.md — check all common names). If no changelog exists, switch to Mode 3 (Create from scratch).

Step 2: Check structure against Keep a Changelog 1.1.0

Verify each of the following. For every violation, note the line number, what's wrong, and cite the source from references/best-practices.md:

1. Header — File starts with # Changelog and optionally a description mentioning Keep a Changelog and Semantic Versioning.
2. Unreleased section — An ## [Unreleased] section exists at the top.
3. Change type headings — Entries use only the six allowed types: Added, Changed, Deprecated, Removed, Fixed, Security. Flag any non-standard headings (e.g., ### Improvements, ### Misc).
4. Version format — Released sections use ## [x.y.z] - YYYY-MM-DD with ISO 8601 dates. Flag ambiguous date formats like 04/19/2026.
5. Reverse chronological order — Newest version appears first.
6. Comparison links — Bottom of file has [unreleased] and version comparison links pointing to the repository's diff URLs.
7. No empty sections — Flag ### Added headings with no entries beneath them.
8. Entry quality — Each entry should describe a user-visible change, not a commit message. Flag entries like "fixed bug" (no context) or entries that are clearly copy-pasted commit messages.
9. Yanked releases — If any release was yanked, it should be marked with [YANKED] after the date.

Step 3: Cross-check with project metadata

• Compare the latest released version in the changelog against version in pyproject.toml (or setup.py, setup.cfg). Flag mismatches.
• If there are commits or code changes since the last release tag that are not reflected in ## [Unreleased], note them.

Step 4: Produce the audit report

Output a markdown table:

Severity levels:

• error — Violates Keep a Changelog spec or Semantic Versioning.
• warning — Deviates from best practice but not spec-breaking.
• info — Suggestion for improvement.

---

Mode 2 — Add a changelog entry

Use when the user says things like "update the changelog", "add this to the changelog", or has just finished a code change.

Step 1: Identify what changed

Ask or infer from context:

• Which files were added, changed, or fixed?
• Is this a new feature (Added), a behavior change (Changed), a bug fix (Fixed), a removal (Removed), a deprecation (Deprecated), or a security fix (Security)?
• Are there new test files? New sample/fixture files?

Step 2: Write the entries

Follow this format for each entry:

- **<file or module>**: Brief description of the user-visible change.
  - Sub-bullet for important details (methods, properties, behavior).
  - Another sub-bullet if needed.

Rules for writing entries:

• Bold the file path — **path/to/file.py**: prefix identifies where the change lives.
• One entry per logical change — do not combine unrelated changes.
• Include test files — new test files get their own Added entry with the test count (e.g., "12 unit tests for…").
• Include sample/fixture files — new or updated data files get their own entry.
• Use the right section — new features → Added, behavior changes → Changed, bug fixes → Fixed, removals → Removed, deprecations → Deprecated, vulnerability fixes → Security.

Step 3: Insert into the changelog

Add the entries under the appropriate ### <Type> heading within ## [Unreleased]. If the heading doesn't exist yet, create it in the canonical order: Added, Changed, Deprecated, Removed, Fixed, Security.

Never modify entries under a released version section.

---

Mode 3 — Create a changelog from scratch

Use when no CHANGELOG.md exists, or when the user asks to "create a changelog" or "initialize a changelog".

Step 1: Determine project state

• Check pyproject.toml (or setup.py) for the current version.
• Check git tags for previous releases.
• Check git log for notable changes.

Step 2: Generate the file

Start with this template:

# 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]

If the project already has released versions (from git tags), add sections for those versions with entries derived from commit messages between tags. Clean up commit messages into proper changelog entries — do not dump raw commit logs.

Add comparison links at the bottom of the file.

Step 3: Present and confirm

Show the generated changelog to the user for review before writing it to disk.

---

Mode 4 — Prepare a release

Use when the user says "prepare a release", "bump the version", "release v1.2.0", or "cut a release".

Step 1: Determine the version bump

Review the entries in ## [Unreleased] and recommend a version bump based on Semantic Versioning:

• MAJOR — if any entry describes a breaking API change, backward-incompatible change, or removal of public functionality.
• MINOR — if entries describe new features, additions, or non-breaking changes to existing functionality.
• PATCH — if entries describe only bug fixes, security patches, or documentation corrections with no API impact.

Present the recommendation and let the user confirm or override.

Step 2: Update the changelog

1. Replace ## [Unreleased] with ## [x.y.z] - YYYY-MM-DD using today's date in ISO 8601 format.
2. Add a new empty ## [Unreleased] section above the new release.
3. Add/update the comparison link at the bottom of the file.

Step 3: Update project metadata

Update the version field in pyproject.toml (or setup.py, setup.cfg) to match the new version. If the project uses a __version__ variable in __init__.py, update that too.

Step 4: Present changes

Show before/after diffs for:

• CHANGELOG.md
• pyproject.toml (or equivalent)
• Any __version__ file

Wait for user approval before writing.

---

What does NOT need a changelog entry

Not every change is user-visible. Skip changelog entries for:

• Internal refactors with no API or behavior change
• Comment-only or docstring-only changes
• CI/CD configuration changes (unless they affect users)
• Developer tooling changes (linter config, pre-commit hooks)
• Dependency version pin updates (unless they fix a user-facing bug)

If unsure, ask the user.

Constraints

• Never edit released sections. Once a version is published, its changelog entries are immutable. If a correction is needed, add a note in the next release.
• Always use ISO 8601 dates — YYYY-MM-DD, never regional formats.
• Changelogs are for humans, not machines. Write clear, concise descriptions of what changed and why it matters. Do not paste commit hashes, PR numbers without context, or raw diff output.
• One logical change per entry. Do not combine "added feature X and fixed bug Y" in a single bullet.
• Follow the project's existing conventions. If the project already uses a specific entry format (e.g., bold file paths, module prefixes), match it. Only suggest format changes during an audit (Mode 1).