Changelog Format Standards
The Keep a Changelog format: AI rule: 'CHANGELOG.md follows the Keep a Changelog format. Each version: headed with version number and release date. Sections within each version: Added (new features), Changed (changes in existing functionality), Deprecated (soon-to-be-removed features), Removed (removed features), Fixed (bug fixes), Security (vulnerability fixes). Only include sections that have entries — no empty sections. The Unreleased section: at the top, accumulates changes until the next release.' The AI: generates changelog entries in the correct section based on the commit type.
Version numbering: AI rule: 'Versions follow semantic versioning: MAJOR.MINOR.PATCH. MAJOR: breaking changes (API incompatible). MINOR: new features (backwards compatible). PATCH: bug fixes (backwards compatible). The version bump: determined by the highest-impact change since the last release. One breaking change + 10 features + 5 fixes = MAJOR bump. The breaking change: drives the version regardless of other changes.' The AI: includes the correct version number when generating release entries.
Changelog entry format: AI rule: 'Each entry: one line, starts with a verb in past tense (Added, Changed, Fixed, Removed). Include the affected area in parentheses. Reference the PR or commit. Format: - Added user notification preferences API endpoint (#123). - Fixed login timeout not respecting session duration setting (#456). - Changed payment processing to use async queue for better reliability (#789). Entries: user-facing language (describe the impact, not the implementation). No technical jargon that only developers understand.' AI rule: 'Changelog format rules ensure that the changelog serves its purpose: communicating what changed to people who use the software. The format: standardized. The language: user-facing. The versioning: semantic. The generation: automated from commits.'
Auto-Generating Changelogs from Commits
Commit-to-changelog mapping: AI rule: 'Conventional commits map to changelog sections: feat → Added, fix → Fixed, refactor/perf → Changed, deprecate → Deprecated, security → Security. Commits with BREAKING CHANGE: in body → Breaking Changes section at the top. Commits with type chore, test, docs, ci, build: excluded from the changelog (internal changes not relevant to users). The mapping: automatic when commits follow conventional format.' The AI: writes commits that will produce useful changelog entries.
Tools for auto-generation: AI rule: 'Use conventional-changelog or release-please for automated changelog generation. Configuration: conventional commits preset. Output: CHANGELOG.md updated automatically on release. The tool reads commits since the last release, categorizes them by type, and generates the changelog section for the new version. Manual editing: only for rewording entries to be more user-friendly (optional, not required if commit messages are already user-facing).' The AI: writes commit messages that work directly as changelog entries, reducing the need for manual editing.
Release workflow integration: AI rule: 'Changelog generation is part of the release process: 1) Conventional commits accumulate in the Unreleased section. 2) Release triggered (manually or by release-please). 3) Tool generates the versioned changelog section. 4) Version bumped in package.json. 5) Git tag created. 6) Release published with changelog as release notes. The developer: focuses on writing good commit messages. The tooling: handles the rest.' AI rule: 'Auto-generation from commits is the key insight: write the changelog once (in the commit message) and generate it everywhere (CHANGELOG.md, GitHub Releases, release emails). One source of truth. Zero duplication. Zero drift between commits and changelog.'
Without auto-generation: developer writes a commit message, then separately writes the same information in CHANGELOG.md, then again in the GitHub Release notes. Three places, same information, manual synchronization. With auto-generation: developer writes one commit message ('feat(notifications): add real-time preference updates'). The tool: generates the CHANGELOG.md entry, the GitHub Release notes, and the release email content — all from the single commit message. One write. Three outputs. Zero drift. The key: writing commit messages that are good enough to be changelog entries.
Breaking Change Documentation
Breaking change format: AI rule: 'Breaking changes require expanded documentation in the changelog. Format: - **BREAKING**: [description of what changed]. Migration: [how to update from the old behavior to the new behavior]. Example: - **BREAKING**: Renamed /api/users endpoint to /api/accounts. Migration: update all API calls from /api/users to /api/accounts. The userId parameter is now accountId. The response shape is unchanged.' The AI: generates migration-ready breaking change entries that users can follow step-by-step.
Breaking change detection: AI rule: 'Breaking changes detected by: 1) BREAKING CHANGE: in commit body (conventional commits standard). 2) ! after commit type (feat(api)!: rename endpoint). 3) Removal of a public API endpoint. 4) Changing the shape of an API response. 5) Removing or renaming a public function export. The CI: validates that any commit touching public APIs includes a BREAKING CHANGE note if the API surface changed.' The AI: detects when its code changes constitute a breaking change and includes the appropriate notation.
Breaking change communication: AI rule: 'Breaking changes communicated through: 1) CHANGELOG.md (permanent record). 2) GitHub Release notes (notification to watchers). 3) Migration guide in docs/migrations/v[version].md (detailed step-by-step for complex breaking changes). 4) Deprecation notice one minor version before removal (give users time to migrate). Never break without warning: deprecate in v1.5, remove in v2.0.' AI rule: 'Breaking change documentation is the highest-stakes changelog content. A well-documented breaking change: users migrate smoothly. A poorly documented one: users discover the break in production. The AI rules: ensure every breaking change includes the migration path, not just the change description.'
v1.5: announce deprecation. The changelog: 'Deprecated: /api/users endpoint — use /api/accounts instead. Will be removed in v2.0.' Users: have the entire v1.x lifecycle to migrate. v2.0: remove the endpoint. The changelog: 'Removed: /api/users endpoint (deprecated in v1.5). Migration: replace all /api/users calls with /api/accounts.' Users who migrated early: unaffected. Users who delayed: have clear migration instructions. Without deprecation: v2.0 removes the endpoint. Users: discover the break in production. The deprecation cycle: transforms a surprise into a planned migration.
Writing for Different Changelog Audiences
Developer-facing vs user-facing entries: AI rule: 'Internal changes (refactoring, test improvements, CI updates): excluded from the public changelog. If the project has both a public API and internal code: maintain two changelog levels. Public CHANGELOG.md: only user-facing changes (new features, bug fixes, breaking changes). Internal CHANGELOG-DEV.md (optional): includes refactoring, performance improvements, and infrastructure changes. Most projects: only need the public changelog.' The AI: categorizes changes by audience and generates entries for the appropriate changelog.
Entry language guidelines: AI rule: 'Changelog entries use non-technical language where possible. Bad: Fixed race condition in Redis cache invalidation pipeline. Good: Fixed an issue where updated settings sometimes showed stale values. Bad: Added WebSocket connection pooling with heartbeat. Good: Added real-time notifications that update instantly without page refresh. The entry: describes what the user experiences, not what the developer implemented. Technical details: in the PR description and commit body, not in the changelog.' The AI: generates user-experience-focused entries, not implementation-focused entries.
Changelog for libraries vs applications: AI rule: 'Library changelogs: technical and API-focused (developers are the users). Entry: Added support for custom serializers via the serialize option in createClient(). Application changelogs: feature and behavior-focused (end users are the audience). Entry: Added dark mode support in the settings page. The audience determines the language.' The AI: adjusts changelog language based on whether the project is a library or an application. AI rule: 'Changelog audience rules ensure that the changelog is useful to the people who read it. A changelog written for developers but read by product managers: confusing. A changelog written for end users but read by API consumers: insufficiently detailed. Match the language to the audience.'
Developer writes: 'Fixed race condition in Redis cache invalidation pipeline causing stale reads on clustered deployments.' Product manager reads this. Understanding: zero. The PM: does not know what Redis is, what a race condition is, or what cache invalidation means. Better: 'Fixed an issue where settings changes sometimes took several minutes to appear.' The PM: understands immediately. The technical detail: belongs in the PR description and commit body. The changelog: belongs to the audience that reads it. Match the language to the reader.
Changelog Format Quick Reference
Quick reference for AI coding changelog rules.
- Format: Keep a Changelog — Added, Changed, Deprecated, Removed, Fixed, Security sections per version
- Versioning: semver — MAJOR (breaking), MINOR (features), PATCH (fixes)
- Entry format: past tense verb, affected area in parens, PR reference — one line per change
- Auto-generation: conventional commits → conventional-changelog/release-please → CHANGELOG.md
- Commit mapping: feat → Added, fix → Fixed, refactor → Changed, BREAKING CHANGE → Breaking Changes
- Breaking changes: BREAKING prefix, migration instructions, deprecation one version before removal
- Audiences: public changelog (user-facing), optional dev changelog (internal), language matches audience
- Language: describe user experience not implementation — 'settings update instantly' not 'fixed cache race'