Manage Changelog

Maintain a project changelog following the Keep a Changelog format. This skill covers creating a new changelog, categorizing entries, managing the [Unreleased] section, and promoting entries to versioned sections upon release. Adapts to R convention (NEWS.md) when detected.

When to Use

Starting a new project that needs a changelog
Adding entries after completing features, fixes, or other changes
Preparing a release by moving Unreleased entries to a versioned section
Reviewing changelog completeness before publishing
Converting a free-form changelog to Keep a Changelog format

Inputs

Required: Project root directory
Required: Description of changes to document (or git log to extract from)
Optional: Target version number (for release promotion)
Optional: Release date (defaults to today)
Optional: Changelog format preference (Keep a Changelog or R NEWS.md)

Procedure

Step 1: Locate or Create Changelog

Search for an existing changelog in the project root.

# Check for common changelog filenames
ls -1 CHANGELOG.md CHANGELOG NEWS.md CHANGES.md HISTORY.md 2>/dev/null

If no changelog exists, create one with the standard header:

# Changelog

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

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

## [Unreleased]

For R packages, use NEWS.md with R convention formatting:

# packagename (development version)

## New features

## Bug fixes

## Minor improvements and fixes

Expected: Changelog file located or created with proper header and an Unreleased section.

On failure: If a changelog exists in a non-standard format, do not overwrite it. Instead, note the format difference and adapt entries to match the existing style.

Step 2: Parse Existing Entries

Read the changelog and identify its structure:

Header/preamble (project name, format description)
[Unreleased] section with pending changes
Versioned sections in reverse chronological order ([1.2.0] before [1.1.0])
Comparison links at the bottom (optional)

For each section, identify the categories present:

Added -- new features
Changed -- changes in existing functionality
Deprecated -- soon-to-be removed features
Removed -- now removed features
Fixed -- bug fixes
Security -- vulnerability fixes

Expected: Changelog structure understood, existing entries inventoried.

On failure: If the changelog is malformed (missing sections, wrong order), note the issues but do not restructure without confirmation. Add new entries correctly and flag structural issues for manual review.

Step 3: Categorize New Changes

For each change to be documented, classify it into one of the six categories:

Category	When to Use	Example Entry
Added	New feature or capability	`- Add CSV export for summary reports`
Changed	Modification to existing feature	`- Change default timeout from 30s to 60s`
Deprecated	Feature marked for future removal	`- Deprecate` old_function()`in favor of`new_function()``
Removed	Feature or capability removed	`- Remove legacy XML parser`
Fixed	Bug fix	`- Fix off-by-one error in pagination`
Security	Vulnerability fix	`- Fix SQL injection in user search (CVE-2026-1234)`

Entry writing guidelines:

Start each entry with a verb in imperative mood (Add, Change, Fix, Remove)
Be specific enough that a user can understand the impact without reading code
Reference issue numbers or CVEs where applicable
Keep entries to one line; use sub-bullets only for complex changes

Expected: Each change assigned to exactly one category with a well-written entry.

On failure: If a change spans multiple categories (e.g., both adds a feature and fixes a bug), create separate entries in each relevant category. If the category is unclear, default to "Changed."

Step 4: Add Entries to Unreleased Section

Insert categorized entries under the [Unreleased] section. Maintain category order: Added, Changed, Deprecated, Removed, Fixed, Security.

## [Unreleased]

### Added

- Add batch processing mode for large datasets
- Add `--dry-run` flag to preview changes without applying

### Fixed

- Fix memory leak when processing files over 1GB
- Fix incorrect timezone handling in date parsing

Only add categories that have entries; do not include empty category headings.

Expected: New entries added under [Unreleased] in the correct categories, maintaining consistent formatting.

On failure: If the Unreleased section does not exist, create it immediately below the header/preamble and above the first versioned section.

Step 5: Promote to Versioned Section on Release

When cutting a release, move all Unreleased entries to a new versioned section:

Create a new section heading: ## [1.3.0] - 2026-02-17
Move all entries from [Unreleased] to the new section
Leave [Unreleased] empty (but keep the heading)
Update comparison links at the bottom of the file

## [Unreleased]

## [1.3.0] - 2026-02-17

### Added

- Add batch processing mode for large datasets

### Fixed

- Fix memory leak when processing files over 1GB

## [1.2.0] - 2026-01-15

### Added

- Add CSV export for summary reports

Update comparison links (if present at bottom):

[Unreleased]: https://github.com/user/repo/compare/v1.3.0...HEAD
[1.3.0]: https://github.com/user/repo/compare/v1.2.0...v1.3.0
[1.2.0]: https://github.com/user/repo/compare/v1.1.0...v1.2.0

For R NEWS.md, use the R convention:

# packagename 1.3.0

## New features

- Add batch processing mode for large datasets

## Bug fixes

- Fix memory leak when processing files over 1GB

# packagename 1.2.0
...

Expected: Unreleased entries moved to a dated versioned section; Unreleased section cleared; comparison links updated.

On failure: If the version number conflicts with an existing section, the version was already released. Check with apply-semantic-versioning to determine the correct version.

Step 6: Validate Changelog Format

Verify the changelog meets format requirements:

Versions are in reverse chronological order (newest first)
Dates follow ISO 8601 format (YYYY-MM-DD)
Each versioned section has at least one categorized entry
No duplicate version sections
Comparison links (if present) match the version sections

# Check for duplicate version sections
grep "^## \[" CHANGELOG.md | sort | uniq -d

# Verify date format
grep "^## \[" CHANGELOG.md | grep -v "Unreleased" | grep -vE "\d{4}-\d{2}-\d{2}"

Expected: Changelog passes all format checks with no warnings.

On failure: Fix any format issues found: reorder sections, correct date formats, remove duplicates. Report issues that require human judgment (e.g., missing entries for known changes).

Validation

Changelog file exists with proper header referencing Keep a Changelog and SemVer
[Unreleased] section exists at the top (below header)
All new entries are categorized into Added/Changed/Deprecated/Removed/Fixed/Security
Entries start with imperative verb and describe user-facing impact
Versioned sections are in reverse chronological order
Dates use ISO 8601 format (YYYY-MM-DD)
No duplicate version sections exist
Comparison links (if used) are correct and up to date
Empty categories are not included (no heading without entries)

Common Pitfalls

Internal-only entries: "Refactored database module" is not useful to users. Focus on user-facing changes. Internal refactors go in commit messages, not changelogs.
Vague entries: "Various bug fixes" tells the user nothing. Each fix should be a specific, descriptive entry.
Forgetting Unreleased: Adding entries directly to a versioned section instead of Unreleased means changes are documented as already released when they are not.
Wrong category: "Fix" that actually adds a new feature. A fix restores expected behavior; a new capability is "Added" even if it was requested as a bug report.
Missing Security entries: Security fixes should always be documented with CVE identifiers when available. Users need to know if they should upgrade urgently.
Changelog drift: Not updating the changelog at the time of the change. Batch-writing entries before release leads to missed or poorly described changes. Write entries alongside code changes.

Related Skills

apply-semantic-versioning -- Determine the version number that pairs with changelog entries
plan-release-cycle -- Define when changelog entries get promoted to versioned sections
commit-changes -- Commit changelog updates with proper messages
release-package-version -- R-specific release workflow including NEWS.md updates
create-github-release -- Use changelog content as GitHub release notes

manage-changelog