Changelog Management

Overview

This skill covers best practices for maintaining project changelogs, including commit tracking, version management, and structured change documentation following the Keep a Changelog standard.

Changelog Structure

Standard Format

# Changelog

## [Unreleased]
### Planned
- [ ] Feature name

## [Version] - YYYY-MM-DD
### Added
- **Feature Name** ([commit](link))
  - Description

### Changed
- **Feature Name** ([commit](link))
  - What changed

### Fixed
- **Bug Description** ([commit](link))
  - What was fixed

### Documentation
- **Document Name** ([commit](link))
  - What was updated

Version Formatting

Semantic Versioning

Format: [MAJOR.MINOR.PATCH]
Breaking Changes: Increment MAJOR (1.0.0 → 2.0.0)
New Features: Increment MINOR (0.1.0 → 0.2.0)
Bug Fixes: Increment PATCH (0.1.0 → 0.1.1)

Date Format

Format: ISO 8601 YYYY-MM-DD
Example: 2025-01-15
Consistency: Always use same format

Commit Tracking

Getting Commit Information

# Short commit hash
git log --oneline -1
# Output: abc1234 feat: add search

# Full commit hash
git rev-parse HEAD
# Output: abc1234567890abcdef1234567890abcdef1234

# Commit for specific file
git log --oneline -1 -- path/to/file.rs

Commit Reference Formats

Short Hash with Link (Recommended):

- **Feature** ([abc1234](https://github.com/user/repo/commit/abc1234))

Multiple Commits:

- **Feature** ([abc1234](link), [def5678](link))

Commit Range:

- **Feature** ([abc1234..def5678](https://github.com/user/repo/compare/abc1234..def5678))

Without Link:

- **Feature** (commit: abc1234)

Change Categories

Added

For new features, functionality, or capabilities:

### Added
- **Search Functionality** ([abc1234](link))
  - Real-time search by title and description
  - Search history with recent searches
  - Keyboard shortcut (Ctrl/Cmd + K)

Changed

For changes to existing functionality:

### Changed
- **Storage Implementation** ([def5678](link)) (2025-02-01)
  - Migrated from localStorage to IndexedDB
  - Improved performance for large datasets
  - Added automatic data migration script

Fixed

For bug fixes:

### Fixed
- **GitHub Pages Deployment** ([ghi9012](link)) (2025-02-01)
  - Fixed `base_path` configuration (added leading slash)
  - Fixed 404.html for client-side routing
  - Fixed file copying to include all subdirectories

Documentation

For documentation updates:

### Documentation
- **Cursor Rules** ([jkl3456](link)) (2025-02-01)
  - Created comprehensive rule structure
  - Added project structure guidelines
  - Added code formatting standards

Workflow Patterns

Adding a New Feature

Develop and commit:

git commit -m "feat: add search functionality"

Get commit hash:

git log --oneline -1
# Output: abc1234 feat: add search functionality

Update CHANGELOG.md:

## [Unreleased]
### Planned
- [x] Add search functionality ✅

## [0.2.0] - 2025-02-01
### Added
- **Search Functionality** ([abc1234](https://github.com/user/repo/commit/abc1234))
  - Real-time search by title and description
  - Search history with recent searches

Update version in Cargo.toml:
```
[package]
version = "0.2.0"
```

Fixing a Bug

Fix and commit:

git commit -m "fix: correct base_path configuration"

Update CHANGELOG.md:

### Fixed
- **GitHub Pages Deployment** ([abc1234](link)) (2025-02-01)
  - Fixed `base_path` configuration (added leading slash)

Breaking Changes

Mark clearly with migration notes:

## [2.0.0] - 2025-03-01

### Changed (Breaking)
- **Storage API** ([abc1234](link)) (2025-03-01)
  - Changed storage key format from `reminders` to `reminders_v2`
  - **Migration Required**: Run migration script before upgrading
  - Old data format no longer supported

Best Practices

DO:

✅ Include commit hashes for all changes
✅ Use clear, descriptive change descriptions
✅ Group related changes together
✅ Include dates for significant changes
✅ Explain the "why" for major changes
✅ Mark breaking changes clearly
✅ Update with every release
✅ Link commits to GitHub (if available)

DON'T:

❌ Don't use vague descriptions
❌ Don't mix different change types in one entry
❌ Don't forget to include dates
❌ Don't skip version numbers
❌ Don't forget commit references
❌ Don't include internal-only changes (unless relevant)

Automation Tips

Generate Commit List

# Get commits since last tag
git log $(git describe --tags --abbrev=0)..HEAD --oneline

# Get commits for a specific version
git log v0.1.0..v0.2.0 --oneline

Extract Commit Messages

# Get commit messages for changelog
git log --pretty=format:"- %s ([%h](https://github.com/user/repo/commit/%H))" v0.1.0..HEAD

Integration with Development Plan

Link CHANGELOG to DEVELOPMENT_PLAN:

### Added
- **Search Functionality** ([abc1234](link))
  - Real-time search by title and description
  - See [DEVELOPMENT_PLAN.md](./DEVELOPMENT_PLAN.md) for details
  - Related issue: #123
  - Related PR: #456

Version Release Process

Pre-Release Checklist

Update CHANGELOG.md with all changes
Include commit references for all entries
Update version in Cargo.toml
Review all changes for accuracy
Check for breaking changes

Release Steps

Finalize CHANGELOG:

## [0.2.0] - 2025-02-01
[All changes with commit references]

Update version:
```
[package]
version = "0.2.0"
```

Create git tag:

git tag -a v0.2.0 -m "Release v0.2.0"
git push origin v0.2.0

Create GitHub release:
- Use CHANGELOG content as release notes
- Link to commit range
- Mark as latest release

Post-Release

Move [Unreleased] items to new version section
Update DEVELOPMENT_PLAN.md with completed features
Update version history section

Resources

Keep a Changelog - Standard format
Semantic Versioning - Version numbering
ISO 8601 - Date format standard
Conventional Commits - Commit message format

changelog-management