Manage Changelog

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:

1. Header/preamble (project name, format description)
2. [Unreleased] section with pending changes
3. Versioned sections in reverse chronological order ([1.2.0] before [1.1.0])
4. 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:

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:

1. Create a new section heading: ## [1.3.0] - 2026-02-17
2. Move all entries from [Unreleased] to the new section
3. Leave [Unreleased] empty (but keep the heading)
4. 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:

1. Versions are in reverse chronological order (newest first)
2. Dates follow ISO 8601 format (YYYY-MM-DD)
3. Each versioned section has at least one categorized entry
4. No duplicate version sections
5. 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