changelog-rfc-29_skill

Overview

This skill enforces RFC-29 Common Changelog format with an Unreleased section extension and automates changelog validation and generation. It validates changelog on commits and in CI, generates changelog entries from git history, and ensures every merged PR is documented. Use it to set up changelog workflows or retrofit existing repositories.

How this skill works

The skill parses CHANGELOG.md into structured releases and groups, then applies validation rules for header, version/date formats, category names/order, and reference presence. It provides scripts to validate format, check that changelog is updated during commits, verify PR coverage, retrofit history into a changelog, and import GitHub releases. Hooks and CI steps call the validation and coverage checks to block merges when rules fail.

When to use it

• Setting up a changelog workflow for a new repository
• Retrofitting an existing project from git tags or releases
• Enforcing changelog updates in pre-commit or pre-push hooks
• Verifying that every merged PR is documented in CI
• Converting other changelog formats (Keep a Changelog) to Common Changelog

Best practices

• Keep an Unreleased section for in-progress changes and add PR references for each entry
• Use the provided scripts (validate, coverage, retrofit, migrate) in automation and CI pipelines
• Follow the category order: Changed, Added, Removed, Fixed — only include categories with changes
• Always include at least one reference (PR number or commit hash) and use **Breaking:** prefix for breaking changes
• Add the changelog check to pre-commit and pre-push hooks so documentation is kept up to date

Example use cases

• Add a pre-commit hook that requires CHANGELOG.md staged when significant files change
• Run retrofit to generate a changelog from tags and commits for an older project
• Use coverage check in CI to fail a pull request when merged PRs are not listed in changelog
• Migrate a Keep a Changelog file to the Common Changelog format using the migrate script
• Import GitHub releases into CHANGELOG.md to create a canonical changelog file