SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsupdate-changelog

update-changelog

Writing & research

View repository

Updated 10-15 21:46

About this skill

Update Changelog

Create or update CHANGELOG.md following the Keep a Changelog 1.1.0 format, using git tags as version boundaries.

CRITICAL: Human-First Entries and Format

  • Do NOT copy commit messages verbatim. Changelogs are for humans -- readers who care about what changed and why, not how the code was modified. Group related commits into logical changes and write each entry as a clear, meaningful description.
  • The [Unreleased] section MUST always be present, even if empty.
  • Versions MUST be in reverse chronological order (newest first), with ISO 8601 dates (YYYY-MM-DD).
  • Omit empty categories -- only include categories that have entries.
  • When updating an existing changelog, preserve any hand-edited entries in existing version sections -- do not overwrite them.

See references/keepachangelog-format.md for the full format specification.

Process

1. Gather git tag and remote info

Run these commands to understand the project's release history:

git tag --sort=-v:refname
git log --oneline --decorate
git remote get-url origin

Collect:

  • All tags sorted by version (descending). Both v1.0.0 and 1.0.0 prefixes are valid -- detect which convention the project uses and stay consistent.
  • The remote URL to construct diff comparison links.
  • The hosting platform (GitHub, GitLab, Bitbucket) to pick the correct comparison URL pattern.

If no tags exist, inform the user and generate only an [Unreleased] section from the full commit history.

2. Check for existing CHANGELOG.md

Look for CHANGELOG.md (case-insensitive) in the project root.

  • Exists: Read it. Preserve any hand-written content. Only add or update version sections that are missing or incomplete.
  • Does not exist: Create a new file from scratch.

3. Build version sections from git history

For each pair of adjacent tags (newest to oldest), extract commits with their full messages:

git log --format="%h %s%n%b" <older-tag>..<newer-tag>

For the oldest tag:

git log --format="%h %s%n%b" <oldest-tag>

For unreleased changes (commits after the latest tag):

git log --format="%h %s%n%b" <latest-tag>..HEAD

Get the tag date for each version:

git log -1 --format=%ai <tag>

4. Synthesize meaningful changelog entries

Do NOT copy commit messages verbatim. Changelogs are for humans -- readers who care about what changed and why, not how the code was modified.

Analyze the full commit messages gathered in step 3 (subject lines and bodies) to understand the intent and impact of each change. Group related commits into logical changes. Multiple commits that together implement one feature become a single entry. A refactor that splits one file into three is one change, not three.

Classify each logical change into exactly one category (in this order of precedence):

Category What belongs here
Added New capabilities users can now do
Changed Existing behavior that now works differently
Deprecated Capabilities that will be removed in a future version
Removed Capabilities that no longer exist
Fixed Broken behavior that now works correctly
Security Vulnerabilities that have been addressed

Omit changes with no user-facing impact (internal refactors, CI tweaks, test additions, doc typo fixes) unless they substantially affect the development experience for contributors.

Write each entry as a clear, meaningful description:

  • Describe what the user can now do or what changed for them, not what files were touched.
  • Provide enough context that a reader unfamiliar with the codebase understands the significance.
  • Consolidate: 5 commits fixing the same parser become one entry like "Fix CSV parser failing on quoted fields with newlines".
  • One entry per line, prefixed with - .

Bad (git log copy-paste):

- Update auth middleware
- Fix bug in login
- Refactor token validation

Good (meaningful for readers):

- Session tokens now refresh automatically 5 minutes before expiry, eliminating unexpected logouts during long sessions
- Fix login failing silently when the email contains uppercase characters

5. Assemble the changelog

Follow this exact structure. See references/keepachangelog-format.md for the full format specification.

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

## [x.y.z] - YYYY-MM-DD

### Added
- Entry

### Fixed
- Entry

[Unreleased]: https://github.com/owner/repo/compare/vx.y.z...HEAD
[x.y.z]: https://github.com/owner/repo/compare/vPREV...vx.y.z

Rules:

  • Versions in reverse chronological order (newest first).
  • Dates in ISO 8601 format (YYYY-MM-DD).
  • Omit empty categories -- only include categories that have entries.
  • The [Unreleased] section is always present, even if empty.
  • Footer contains comparison links for every version.
  • The first (oldest) release links to its tag, not a comparison.

6. Write the file

Write CHANGELOG.md to the project root. After writing, briefly confirm what was generated (number of versions, notable entries).

Updating an existing changelog

When CHANGELOG.md already exists:

  1. Parse existing version sections and their entries.
  2. Identify tags not yet represented in the changelog.
  3. Add only missing version sections in the correct chronological position.
  4. Refresh the [Unreleased] section with commits after the latest tag.
  5. Update footer diff links to include all versions.
  6. Preserve any hand-edited entries in existing version sections -- do not overwrite them.

References

  • references/keepachangelog-format.md -- Full format specification, diff link patterns, and category ordering