Add Cursor commands for automated tag-and-release and PR version bumping

[gerchowl]

Description

Add Cursor commands to automate git tag creation, GitHub release workflow, and intelligent version bumping during PR creation.

Motivation

Currently requires manual steps:

1. Version bumping: Manual decision on major/minor/patch and running make bump-*
2. Tag and release: Manual git commands and GitHub release creation

This should be streamlined with intelligent Cursor commands.

Proposed Commands

1. /tag-and-release

Automates the complete tag and release workflow:

Validation Steps:

• ✅ Verify on main branch with clean working directory
• ✅ Get current version using make version (reads from pyproject.toml)
• ✅ Confirm version is consecutive to existing git tag (X.Y.Z format)
• ✅ Validate CHANGELOG.md follows Keep a Changelog format:
  • Version format: ## [X.Y.Z] - YYYY-MM-DD
  • Required sections: Added, Changed, Deprecated, Removed, Fixed, Security
  • Most recent version at top
  • Entries under current version

Actions:

• Creates annotated git tag with release notes from CHANGELOG.md
• Pushes tag to remote
• Creates GitHub release with formatted notes from CHANGELOG

Usage:

/tag-and-release

2. /create-pr (Enhanced)

Update existing PR command to include intelligent version bumping:

Version Analysis:

• Examine git tag/version history
• Analyze changes in the branch
• Suggest appropriate version bump following Semantic Versioning:
  • MAJOR (X.0.0): Breaking changes (incompatible API changes)
  • MINOR (0.X.0): New features (backward compatible)
  • PATCH (0.0.X): Bug fixes (backward compatible)

Version Bump Workflow:

• Present suggestion: "Based on changes, suggest: PATCH bump (0.3.3 → 0.3.4)"
• Confirm with user
• Execute appropriate command:
  • make bump-patch (0.3.3 → 0.3.4)
  • make bump-minor (0.3.3 → 0.4.0)
  • make bump-major (0.3.3 → 1.0.0)
• Prompt user to update CHANGELOG.md with actual changes
• Commit version bump
• Create PR with updated version

Requirements

/tag-and-release Requirements

• Use make version to get current version from pyproject.toml
• Validate version matches existing git tag pattern (X.Y.Z)
• Check CHANGELOG.md format compliance:
  • Current version entry exists: ## [X.Y.Z] - YYYY-MM-DD
  • Has at least one category (Added/Changed/Fixed/etc.)
  • Version date is valid
• Extract release notes from CHANGELOG.md for current version
• Create annotated git tag
• Push tag to remote
• Create GitHub release with:
  • Title: "Release X.Y.Z - Feature Name"
  • Body: Formatted notes from CHANGELOG
  • Comparison link
• Verify prerequisites (branch, working directory state)
• Clear error messages if validation fails

/create-pr Enhancement Requirements

• Analyze git tag history (git tag -l | sort -V)
• Get current version (make version)
• Analyze commit messages in branch for:
  • Breaking changes (BREAKING CHANGE in commit body)
  • New features (feat: commits)
  • Bug fixes (fix: commits)
• Suggest version bump based on Semantic Versioning
• Present suggestion with explanation
• Confirm with user which bump to apply
• Execute make bump-patch/bump-minor/bump-major
• Remind user to update CHANGELOG.md
• Include version bump in PR

Keep a Changelog Format

Version entries must follow:

## [X.Y.Z] - YYYY-MM-DD

### Added
- New features

### Changed
- Changes to existing functionality

### Deprecated
- Soon-to-be removed features

### Removed
- Removed features

### Fixed
- Bug fixes

### Security
- Security fixes

Semantic Versioning Rules

Given version MAJOR.MINOR.PATCH (e.g., 1.4.2):

• MAJOR: Increment for incompatible API changes (breaking changes)
• MINOR: Increment for new functionality (backward compatible)
• PATCH: Increment for bug fixes (backward compatible)
• Never reuse version numbers
• Start at 0.1.0 for initial development

Integration with Version Management

Complete workflow:

1. Work on feature branch
2. /create-pr → Analyzes changes, suggests version bump, updates version
3. PR review and merge
4. /tag-and-release → Validates and creates tag + GitHub release

Implementation Location

• New command: .cursor/commands/tag-and-release.md
• Update existing: .cursor/commands/create-pr.md

Reference existing:

• .cursor/commands/git-commit.md
• docs/VERSION_MANAGEMENT.md

Benefits

• ✅ Automated version bump suggestions based on changes
• ✅ Enforces Keep a Changelog format
• ✅ Enforces Semantic Versioning rules
• ✅ Validates version continuity
• ✅ Streamlines release workflow
• ✅ Reduces manual steps and potential errors
• ✅ Consistent release notes formatting
• ✅ Faster, safer releases