Changelog Management

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

1. Develop and commit:

   git commit -m "feat: add search functionality"
   

2. Get commit hash:

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

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

4. Update version in Cargo.toml:

   [package]
   version = "0.2.0"
   

Fixing a Bug

1. Fix and commit:

   git commit -m "fix: correct base_path configuration"
   

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

1. Finalize CHANGELOG:

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

2. Update version:

   [package]
   version = "0.2.0"
   

3. Create git tag:

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

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

Converted and distributed by TomeVault — claim your Tome and manage your conversions.