# Version Synchronization and Changelog Management

> **Agent role**: Reference this file for version synchronization
> requirements and changelog management.

## Version Sync Checklist (Before Commit)

- [ ] `package.json` version matches latest `CHANGELOG.md` entry
- [ ] New version follows semantic versioning
  (MAJOR.MINOR.PATCH[-PRERELEASE])
- [ ] Changelog entry includes all significant changes since last version
- [ ] Version bump commit message follows `build(version): bump to X.Y.Z`
  format
- [ ] Breaking changes properly documented with migration notes
- [ ] Alert developer in chat message that version has been updated

## Version Change Detection

- **Check for version changes** in staged/unstaged `package.json`
- **Alert developer** if version changed but changelog not updated
- **Suggest changelog update** with proper format and content
- **Validate semantic versioning** compliance

## Implementation Notes

### Version Detection

- Compare `package.json` version field with latest changelog entry
- Use semantic versioning validation
- Check for pre-release version consistency

### Semantic Validation

- Ensure version follows `X.Y.Z[-PRERELEASE]` format
- Validate major.minor.patch components
- Handle pre-release suffixes (beta, alpha, rc)

### Changelog Format

- Follow [Keep a Changelog](https://keepachangelog.com/) standards
- Use consistent section headers
- Include breaking change notes
- Maintain chronological order

### Breaking Changes

- Use `!` in commit message
- Include `BREAKING CHANGE:` in changelog
- Provide migration notes
- Document impact clearly

### Pre-release Versions

- Include beta/alpha/rc suffixes consistently
- Update both `package.json` and changelog
- Maintain version number alignment
- Document pre-release status

## Changelog Sections

### Added

- New features
- New capabilities
- New dependencies

### Changed

- Changes in existing functionality
- API changes
- Performance improvements

### Deprecated

- Soon-to-be removed features
- Migration paths
- Sunset timelines

### Removed

- Removed features
- Breaking changes
- Deprecated items

### Fixed

- Bug fixes
- Security patches
- Performance fixes

### Security

- Security vulnerabilities
- CVE references
- Mitigation steps

## Version Bump Guidelines

### Patch (X.Y.Z+1)

- Bug fixes
- Documentation updates
- Minor improvements

### Minor (X.Y+1.Z)

- New features
- Backward-compatible changes
- Significant improvements

### Major (X+1.Y.Z)

- Breaking changes
- Major API changes
- Incompatible changes

## Pre-release Guidelines

### Beta Versions

- Feature complete
- Testing phase
- API stable

### Alpha Versions

- Early development
- API may change
- Limited testing

### Release Candidates

- Final testing
- API frozen
- Production ready

---

**See also**:

- `.cursor/rules/workflow/version_control.mdc` for core version
  control principles
- `.cursor/rules/workflow/commit_messages.mdc` for commit message
  format

**Status**: Active version synchronization guide
**Priority**: High
**Estimated Effort**: Ongoing reference
**Dependencies**: version_control.mdc
**Stakeholders**: Development team, Release team

## Model Implementation Checklist

### Before Version Changes

- [ ] **Version Review**: Check current version in `package.json` and `CHANGELOG.md`
- [ ] **Change Assessment**: Identify what type of version bump is needed (patch/minor/major)
- [ ] **Breaking Changes**: Review if any changes are breaking and require
  major version
- [ ] **Pre-release Status**: Determine if this should be a pre-release version

### During Version Synchronization

- [ ] **Semantic Validation**: Ensure version follows `X.Y.Z[-PRERELEASE]` format
- [ ] **Package Update**: Update `package.json` version field
- [ ] **Changelog Entry**: Add entry to `CHANGELOG.md` following Keep a Changelog
  format
- [ ] **Breaking Changes**: Document breaking changes with migration notes
  if applicable

### After Version Changes

- [ ] **Commit Format**: Use `build(version): bump to X.Y.Z` commit message format
- [ ] **Developer Alert**: Alert developer that version has been updated
- [ ] **Validation**: Verify `package.json` and `CHANGELOG.md` are in sync
- [ ] **Pre-release Handling**: Ensure pre-release versions are consistently formatted