You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
176 lines
4.2 KiB
176 lines
4.2 KiB
# 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
|
|
|