Changelog Rules

Source: docs/rules/changelog.md Enforcement: Pre-commit (advisory) + CI (changelog:check) Owner: docs-librarian

Core Principle

Every commit that changes functionality must include a changelog entry.

The changelog is how we communicate changes to users and maintain a historical record of the project's evolution. Keeping it up-to-date at commit time (rather than retroactively) ensures accuracy and reduces release overhead.

Rules

ID	Rule	Description
CHG-001	Update on commit	Commits changing functionality must update the current month's changelog (`docs/changelog/MM-YYYY.md`)
CHG-002	Category matching	Entries must use correct category (Features, Bug Fixes, etc.)
CHG-003	Scope prefix	Entries should include scope in bold (e.g., Admin Dashboard:)
CHG-004	Date grouping	New entries go under today's date section
CHG-005	Imperative mood	Use imperative verbs (Add, Fix, Update, Remove, Refactor)

What Requires a Changelog Entry

Change Type	Requires Entry?	Category
New feature	✅ Yes	Features
Bug fix	✅ Yes	Bug Fixes
Breaking change	✅ Yes	Breaking Changes
Deprecation	✅ Yes	Deprecations
Performance improvement	✅ Yes	Performance
Security fix	✅ Yes	Security
Refactoring (user-visible)	✅ Yes	Refactoring
Documentation updates	⚠️ If significant	Documentation
Internal refactoring	❌ No	—
Test additions only	❌ No	—
CI/CD changes	⚠️ If user-affecting	CI/CD
Dependency updates	⚠️ If notable	Maintenance

What Does NOT Require a Changelog Entry

Internal code cleanup with no behavior change
Adding/updating tests only
Fixing typos in code comments
Updating development tooling
Changes to .gitignore, editor configs, etc.
Draft documentation not yet published

Entry Format

Entries follow this structure:

## {Date in Month Day, Year format}

### {Category}

- **{Scope}**: {Description in imperative mood}

Example

## January 31, 2026

### Features

- **UI Components**: Add password visibility toggle to auth forms
- **Admin Dashboard**: Add bulk user export functionality

### Bug Fixes

- **Database**: Fix race condition in queue processing

Scopes

Use existing scope names or add new ones as needed:

Scope	Description
UI Components	`packages/ui` changes
Admin Dashboard	`apps/admin` changes
Web App	`apps/web` changes
Database	Schema, migrations, queries
API	API endpoints and contracts
Workers	Background job processors
Claude Agents	`.claude/agents` changes
Documentation	`docs/` changes
Scripts	Build and utility scripts
Public Site	`apps/public` changes

Workflow

Before committing, check if your changes require a changelog entry
Open the current month's file (e.g. docs/changelog/02-2026.md)
Find or create today's date section
Add entry under the appropriate category
Commit both your changes and the changelog update

Generating Changelog

# Auto-generate from recent commits (fills gaps)
bun run changelog:generate

# This is a helper, not a replacement for manual entries

Pre-commit Reminder

When Claude Code commits changes that require a changelog entry, it should:

Check if the current month's changelog file is already staged
If not, remind about the changelog requirement
Add the changelog entry before completing the commit

This is enforced as an advisory rule — Claude should proactively update the changelog rather than waiting to be reminded.

Release Process

When releasing:

Changelogs are organized by month (MM-YYYY.md). At the start of each month, changelog:generate automatically locks the previous month's file (status: locked) and creates the new month's file. For versioned releases, create a {version}.md file and reference the relevant monthly files.

See release-manager agent for full release workflow.

#Changelog Rules

#Core Principle

#Rules

#What Requires a Changelog Entry

#What Does NOT Require a Changelog Entry

#Entry Format

#Example

#Categories

#Scopes

#Workflow

#Generating Changelog

#Pre-commit Reminder

#Release Process