Changelog (RFC-29)

Changelog (RFC-29)

Enforce and validate changelogs following the Common Changelog specification with an Unreleased section extension for in-progress work.

When to Use This Skill

• Setting up changelog workflow in a new repository
• Retrofitting changelog from git history
• Validating changelog format in pre-commit/​pre-push hooks
• Ensuring PR coverage in changelog during CI
• Understanding Common Changelog format requirements

Skill Contents

Sections

• When to Use This Skill (L25-L32)
• Quick Start (L73-L106)
• Format Specification (L107-L164)
• Validation Rules (L165-L194)
• Scripts (L195-L282)
• Migration (L283-L315)
• Integration (L316-L373)
• Exclusions (L374-L399)
• Related Skills (L400-L407)
• Troubleshooting (L408-L445)

Available Resources

📚 references/​ - Detailed documentation

• common changelog spec
• hallmark feature analysis
• migration guide
• unreleased extension

🔧 scripts/​ - Automation scripts

• check updated
• constants
• coverage
• import releases
• migrate
• parse
• retrofit
• semver
• validate

📦 assets/​ - Templates and resources

• changelog template
• exclusion patterns

---

Quick Start

Creating a new CHANGELOG.md

Copy the template and customize:

cp global/​skills/​changelog-rfc-29/​assets/​changelog-template.md CHANGELOG.md

Validating an existing changelog

pnpm run skills:changelog
# or
node .scripts/​skills-cli.ts changelog validate

Checking PR coverage

pnpm run skills:changelog:coverage
# or
node .scripts/​skills-cli.ts changelog coverage

Retrofitting from git history

pnpm run skills:changelog:retrofit
# or
node .scripts/​skills-cli.ts changelog retrofit

Format Specification

File Structure

# Changelog

> Optional description or note about the changelog format.

## [Unreleased]

### Added

- Add new feature ([#123](https://github.com/​org/​repo/​pull/​123))

## [2.0.0] - 2026-01-19

_Optional notice about this release._

### Changed

- **Breaking:** Major refactor ([#100](https://github.com/​org/​repo/​pull/​100))

### Added

- Add feature X ([#95](https://github.com/​org/​repo/​pull/​95))

### Fixed

- Fix bug Y ([#90](https://github.com/​org/​repo/​pull/​90))

[Unreleased]: https://github.com/​org/​repo/​compare/​v2.0.0...HEAD
[2.0.0]: https://github.com/​org/​repo/​releases/​tag/​v2.0.0

Category Order

Categories MUST appear in this order (only include those with changes):

1. Changed - modifications to existing functionality
2. Added - new features
3. Removed - removed features
4. Fixed - bug fixes

Change Format

Each change must:

1. Start with imperative verb (Add, Fix, Remove, Update, etc.)
2. Include at least one reference (PR number or commit hash)
3. Use **Breaking:** prefix for breaking changes

- Add user authentication ([#45](https://github.com/​org/​repo/​pull/​45))
- **Breaking:** Remove deprecated API ([#50](https://github.com/​org/​repo/​pull/​50))
- Fix memory leak in worker pool ([`abc1234`](https://github.com/​org/​repo/​commit/​abc1234))

Validation Rules

Format Validation

Pre-commit Check

When committing, the changelog check:

1. Gets list of staged files
2. Filters out excluded paths (tests, config, generated files)
3. If significant files are staged, requires CHANGELOG.md to also be staged

Coverage Validation

Ensures every merged PR is documented:

1. Extracts PR numbers from git history
2. Extracts PR numbers from CHANGELOG.md
3. Reports any PRs missing from changelog

Scripts

parse.js

Parse CHANGELOG.md into structured data:

import { parseChangelog, extractReferences, parseVersion } from './​scripts/​parse.ts';

const content = fs.readFileSync('CHANGELOG.md', 'utf-8');
const parsed = parseChangelog(content);

// parsed = {
//   title: 'Changelog',
//   releases: [
//     { version: 'Unreleased', date: null, groups: [...] },
//     { version: '2.0.0', date: '2026-01-19', notice: '...', groups: [...] }
//   ]
// }

validate.js

Validate changelog format:

import { validateChangelog } from './​scripts/​validate.ts';

const result = await validateChangelog('/​path/​to/​repo');
// result = { passed: true/​false, errors: [], warnings: [] }

check-updated.js

Pre-commit hook integration:

import { checkChangelogUpdated } from './​scripts/​check-updated.ts';

const result = await checkChangelogUpdated('/​path/​to/​repo');
// result = { passed: true/​false, message: '...', errors: [] }

retrofit.js

Generate changelog from git history:

import { retrofitChangelog } from './​scripts/​retrofit.ts';

const result = await retrofitChangelog({
  rootDir: '/​path/​to/​repo',
  version: '2.0.0',
  date: '2026-01-19',
  repoUrl: 'https://github.com/​org/​repo'
});
// result = { markdown: '...', prCount: 106, categorized: {...} }

coverage.js

Validate PR coverage:

import { validateCoverage } from './​scripts/​coverage.ts';

const result = await validateCoverage('/​path/​to/​repo');
// result = { passed: true/​false, missingPRs: [], extraPRs: [] }

migrate.js

Convert existing changelogs to Common Changelog format:

node global/​skills/​changelog-rfc-29/​scripts/​migrate.ts --input CHANGELOG.md --dry-run
node global/​skills/​changelog-rfc-29/​scripts/​migrate.ts --input CHANGELOG.md --output CHANGELOG.new.md

import-releases.js

Import GitHub releases as changelog entries:

node global/​skills/​changelog-rfc-29/​scripts/​import-releases.ts --repo bitsoex/​my-repo --dry-run
node global/​skills/​changelog-rfc-29/​scripts/​import-releases.ts --repo bitsoex/​my-repo --output CHANGELOG.md

Migration

For repositories with existing changelogs or release history, see the Migration Guide.

Migration Scenarios

Converting from Keep a Changelog

# Preview changes
node global/​skills/​changelog-rfc-29/​scripts/​migrate.ts --input CHANGELOG.md --dry-run

# Convert in place
node global/​skills/​changelog-rfc-29/​scripts/​migrate.ts --input CHANGELOG.md

Importing GitHub Releases

# Preview import
node global/​skills/​changelog-rfc-29/​scripts/​import-releases.ts --repo bitsoex/​my-repo --dry-run

# Generate changelog from releases
node global/​skills/​changelog-rfc-29/​scripts/​import-releases.ts --repo bitsoex/​my-repo --output CHANGELOG.md

Integration

Pre-commit Hook

Add to .scripts/​lib/​validation.ts:

{
  name: 'Changelog updated',
  command: null,
  customCheck: 'checkChangelogUpdated',
  scope: 'pre-commit',
  blocking: true,
  required: true
}

Pre-push Hook

Add to .scripts/​lib/​validation.ts:

{
  name: 'Changelog format',
  command: ['node', '.scripts/​skills-cli.ts', 'changelog', 'validate'],
  scope: 'pre-push',
  blocking: true,
  required: true
}

CI Workflow

Add to .github/​workflows/​ci.yaml:

- name: Validate Changelog Format
  if: github.event_name == 'pull_request'
  run: pnpm run skills:changelog

- name: Validate PR Coverage
  if: github.event_name == 'pull_request'
  run: pnpm run skills:changelog:coverage

Package.json Scripts

{
  "scripts": {
    "skills:changelog": "node .scripts/​skills-cli.ts changelog validate",
    "skills:changelog:check": "node .scripts/​skills-cli.ts changelog check-updated",
    "skills:changelog:coverage": "node .scripts/​skills-cli.ts changelog coverage",
    "skills:changelog:retrofit": "node .scripts/​skills-cli.ts changelog retrofit"
  }
}

Exclusions

Files matching these patterns do NOT require changelog updates.

See assets/​exclusion-patterns.json for the full list.

Infrastructure

• .github/ - CI/​CD workflows
• .gitignore, .nvmrc - config files
• pnpm-lock.yaml - lock files

Tests

• tests/ - test files only

Generated Content

• .tmp/, coverage/, output/ - build outputs
• .claude/​skills/ - distributed content

Configuration

• vitest.config.js, eslint.config.js - tooling config
• .coderabbit.yaml, .doclinterrc.yml - linter config

Related Skills

Troubleshooting

"CHANGELOG.md must be updated"

Your commit includes significant files but CHANGELOG.md is not staged.

Fix: Add an entry to the [Unreleased] section:

## [Unreleased]

### Added

- Describe your change ([#YOUR_PR](https://github.com/​org/​repo/​pull/​YOUR_PR))

"Category X is out of order"

Categories must appear in order: Changed > Added > Removed > Fixed.

Fix: Reorder your categories to match the expected order.

"Change has no reference"

Every change must reference a PR or commit.

Fix: Add a reference in parentheses:

- Your change description ([#123](https://github.com/​org/​repo/​pull/​123))

"Invalid version format"

Version must be valid semver without 'v' prefix.

Good: ## [2.0.0] - 2026-01-19 Bad: ## [v2.0.0] - 2026-01-19

<!-- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY --> <!-- Source: bitsoex/​ai-code-instructions → global/​skills/​changelog-rfc-29/​SKILL.md --> <!-- To modify, edit the source file and run the distribution workflow -->