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.

适用场景

• 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

输入

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

步骤

第 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

预期结果： Changelog file located or created with proper header and an Unreleased section.

失败处理： 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.

第 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

预期结果： Changelog structure understood, existing entries inventoried.

失败处理： 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.

第 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 ofnew_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

预期结果： Each change assigned to exactly one category with a well-written entry.

失败处理： 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."

第 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.

预期结果： New entries added under [Unreleased] in the correct categories, maintaining consistent formatting.

失败处理： If the Unreleased section does not exist, create it immediately below the header/preamble and above the first versioned section.

第 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
...

预期结果： Unreleased entries moved to a dated versioned section; Unreleased section cleared; comparison links updated.

失败处理： If the version number conflicts with an existing section, the version was already released. Check with apply-semantic-versioning to determine the correct version.

第 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}"

预期结果： Changelog passes all format checks with no warnings.

失败处理： 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).

验证清单

• 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)

常见问题

• 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.

相关技能

• 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