Versioning and Changelog Guide

Single Source of Truth

The project maintains a single source changelog at the root level:

• /CHANGELOG.md - The authoritative changelog for all releases (edit this one)
• /docs/changelog.md - Auto-generated copy for documentation (do not edit)

Version Management

Updating Version

When releasing a new version:

1. Update the version using npm (this automatically syncs version across files):

   npm version patch  # for bug fixes (1.0.0 -> 1.0.1)
   npm version minor  # for new features (1.0.0 -> 1.1.0)
   npm version major  # for breaking changes (1.0.0 -> 2.0.0)

2. Update CHANGELOG.md with the new version entry following Keep a Changelog format:

   ## [X.Y.Z] - YYYY-MM-DD
   
   ### Added
   - New features
   
   ### Changed
   - Changes to existing functionality
   
   ### Fixed
   - Bug fixes
   
   ### Removed
   - Removed features

3. Commit and push the changes:

   git push && git push --tags

Version Sync

The npm version command automatically runs sync-version.js which:

• Updates the version badge in README.md
• Checks if CHANGELOG.md has an entry for the new version
• Syncs /CHANGELOG.md to /docs/changelog.md
• Ensures consistency across all documentation

Additionally, the build process (npm run build) also:

• Syncs /CHANGELOG.md to /docs/changelog.md
• Ensures docs always have the latest changelog

Version Locations

Version information is automatically synchronized to:

• package.json - Source of truth for version
• README.md - Version badge
• Any future documentation that needs version info

Changelog Best Practices

1. Update CHANGELOG.md BEFORE releasing - Don't forget to document changes
2. Use semantic versioning - Major.Minor.Patch
3. Group changes by type - Added, Changed, Fixed, Removed
4. Include dates - Use YYYY-MM-DD format
5. Be descriptive - Help users understand the impact of changes

Common Mistakes to Avoid

• ❌ Don't edit /docs/changelog.md directly (it's auto-generated)
• ❌ Don't manually update version numbers in multiple files
• ❌ Don't forget to update CHANGELOG.md when releasing
• ❌ Don't use inconsistent date formats
• ❌ Don't commit /docs/changelog.md (it's in .gitignore)

Example Workflow

# 1. Make your changes and commit them
git add .
git commit -m "feat: add new awesome feature"

# 2. Update CHANGELOG.md with your changes
# Edit CHANGELOG.md and add entry for the new version

# 3. Bump version (this runs sync-version automatically)
npm version minor

# 4. Push changes and tags
git push && git push --tags