Project Change Log

Automatically maintain a CHANGELOG.md file following the Keep a Changelog standard.

When to Use

• After creating a commit
• When /commit command is executed
• When user asks to update changelog
• When releasing a new version
• When CHANGELOG.md has grown large (rotate old releases into archives — see Keeping the changelog small)

Changelog Format

The standard format is CHANGELOG.md in the project root, following Keep a Changelog:

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/),
and this project adheres to [Semantic Versioning](https://semver.org/).

## [Unreleased]

### Added
- New feature description

### Changed
- Change description

### Fixed
- Bug fix description

## [1.0.0] - 2026-01-04

### Added
- Initial release features

Change Categories

Category	Description
Added	New features
Changed	Changes in existing functionality
Deprecated	Soon-to-be removed features
Removed	Removed features
Fixed	Bug fixes
Security	Vulnerability fixes

Process

1. Detect Changelog

Check if CHANGELOG.md exists in project root:

• If exists: Read current content
• If not: Create with template

2. Analyze Commit

Extract from the commit:

• Type: feat, fix, docs, etc.
• Scope: Affected area
• Description: What changed
• Date: Current date (YYYY-MM-DD)
• Author: From git config

3. Map Commit Type to Category

Commit Type	Changelog Category
feat	Added
fix	Fixed
docs	Changed
style	Changed
refactor	Changed
perf	Changed
test	Changed
build	Changed
ci	Changed
chore	Changed
security	Security
deprecate	Deprecated
remove	Removed

4. Update Changelog

Add entry under [Unreleased] section in appropriate category:

## [Unreleased]

### Added
- New entry here with description

5. Version Release

When releasing a version:

1. Move [Unreleased] content to new version section
2. Add version number and date
3. Create new empty [Unreleased] section
4. Rotate old releases so the file stays small — run the archive script (it's a no-op until there are more than 20 versions):

python3 .claude/skills/project-change-log/scripts/rotate_changelog.py --apply

Keeping the changelog small (archiving)

A single CHANGELOG.md grows without bound — one real project reached 197 releases / 2,508 lines / 420 KB. To keep it readable, rotate old releases into per-major archive files.

Policy: keep [Unreleased] + the newest 20 versions in CHANGELOG.md; move older versions into changelog/CHANGELOG-<major>.x.md (e.g. changelog/CHANGELOG-1.x.md), linked from an ## Older releases index at the bottom of the main file.

CHANGELOG.md                 # title + intro + [Unreleased] + newest 20 + index
changelog/
  CHANGELOG-1.x.md           # archived 1.x releases, newest-first
  CHANGELOG-2.x.md           # created when a 2.x release is first rotated out

Use the helper script — safe by default (dry run unless --apply), Python 3 stdlib only, idempotent, and guaranteed not to drop or duplicate any release:

# Preview what would move (no writes):
python3 .claude/skills/project-change-log/scripts/rotate_changelog.py

# Rotate for real:
python3 .claude/skills/project-change-log/scripts/rotate_changelog.py --apply

Run it as the last step of a version release (no-op below 20 versions) or any time the file feels large.

First-time adoption on an existing project (e.g. after this skill is added or updated): run the dry run first and confirm the reported version count looks right, then --apply once and commit the new changelog/ directory with the trimmed CHANGELOG.md in a single commit. It's idempotent, so re-running after later skill updates is safe. If the dry run reports 0/too few versions, the file uses a non-standard heading format — normalize headings to ## [x.y.z] - YYYY-MM-DD first. Full steps + troubleshooting: references/archiving.md.

Flags: --keep N (default 20), --dir changelog, --file CHANGELOG.md. Full details, behavior guarantees, and edge cases: see references/archiving.md.

Entry Format

Each entry should be:

• One line per change
• Start with capital letter
• No period at end
• Include scope if relevant: **scope**: description

Examples:

### Added
- **auth**: OAuth2 login with Google and GitHub
- User profile settings page
- Dark mode toggle

### Fixed
- **api**: Handle null response in user endpoint
- Memory leak in websocket connections

Template

Initial CHANGELOG.md 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/),
and this project adheres to [Semantic Versioning](https://semver.org/).

## [Unreleased]

### Added

### Changed

### Fixed

Integration with Commit

After each commit:

1. Parse commit message for type and description
2. Determine changelog category
3. Add entry under [Unreleased]
4. Stage CHANGELOG.md (do not create separate commit)

Examples

Example 1: Feature Commit

Commit: feat(auth): add OAuth2 login support

Changelog Entry:

### Added
- **auth**: OAuth2 login support

Example 2: Bug Fix

Commit: fix(api): handle null response in user endpoint

Changelog Entry:

### Fixed
- **api**: Handle null response in user endpoint

Example 3: Version Release

Before:

## [Unreleased]

### Added
- Feature A
- Feature B

### Fixed
- Bug fix X

After releasing v1.2.0:

## [Unreleased]

## [1.2.0] - 2026-01-04

### Added
- Feature A
- Feature B

### Fixed
- Bug fix X