petekp/docs-changelog

Docs Changelog

Write a new changelog entry by reviewing commits since the last documented entry, categorizing changes, and appending a well-written entry in Keep a Changelog format.

Workflow

1. Find the changelog file

Search for the changelog in common locations:

CHANGELOG.md
changelog.md
docs/changelog.md
docs/CHANGELOG.md
src/pages/changelog.md
src/content/changelog.mdx
content/changelog.md

Use glob with patterns like **/changelog.{md,mdx} and **/CHANGELOG.{md,mdx} if not found in standard locations. If multiple candidates exist, ask the user which one to use.

2. Parse the last entry

Read the changelog file and extract the most recent version header. The header format is:

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

Extract:

• Version number (e.g., 1.2.0) — for determining the next version
• Date (e.g., 2025-01-15) — for scoping the git log

If the changelog is empty or has only an [Unreleased] header, use the repo's earliest tag or first commit as the boundary.

3. Gather commits

Run:

git log --oneline --no-merges --after="YYYY-MM-DD" HEAD

Where YYYY-MM-DD is the date from the last changelog entry. Also check tags:

git tag -l --sort=-creatordate | head -5

If there's a tag newer than the last changelog entry, use that as the new version number. Otherwise, ask the user what version this entry should be.

4. Categorize changes

Review each commit and assign it to one Keep a Changelog category:

| Category | What belongs here | |---|---| | Added | New features, new pages, new API endpoints | | Changed | Updates to existing functionality, behavior changes, dependency updates | | Deprecated | Features marked for future removal | | Removed | Deleted features, removed pages, dropped support | | Fixed | Bug fixes, typo corrections, broken link repairs | | Security | Vulnerability patches, security improvements |

Categorization rules:

• Read the diff when a commit message is ambiguous — the code tells the truth
• Group related commits into a single bullet (e.g., three typo-fix commits become one "Fixed typos across documentation" entry)
• Skip commits that are purely internal (CI config, linting, formatting-only) unless they affect user-visible behavior
• Skip merge commits and version bump commits

5. Write the entry

Insert the new entry directly below the # Changelog header (or below ## [Unreleased] if present). Use this exact structure — omit any category section that has no items:

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

### Added

- Brief, human-readable description of what was added

### Changed

- Brief description of what changed

### Fixed

- Brief description of what was fixed

Writing rules:

• Each bullet is one sentence, starting with a past-tense verb (Added, Updated, Fixed, Removed)
• Write for the end user of the documentation site, not for developers
• Link to relevant pages or PRs where helpful: Fixed broken link on [Getting Started](/docs/getting-started) page
• Keep entries scannable — no paragraphs, no sub-bullets
• Use the project's existing tone (scan prior entries to match)
• Today's date for the entry date unless the user specifies otherwise

6. Verify

After writing the entry:

• Confirm the entry is in reverse chronological order (newest first)
• Check that version link references at the bottom of the file are updated if the project uses them (e.g., [1.3.0]: https://github.com/org/repo/compare/v1.2.0...v1.3.0)
• Read the final file to ensure formatting is clean

Present the new entry to the user for review before considering the task complete.