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 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
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
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 entriesplan-release-cycle -- Define when changelog entries get promoted to versioned sectionscommit-changes -- Commit changelog updates with proper messagesrelease-package-version -- R-specific release workflow including NEWS.md updatescreate-github-release -- Use changelog content as GitHub release notes