Instruction file imported from cdalsoniii/brightpath-coder (.cursor/rules/040-release-management.mdc). Copyright stays with the author.

Release Management

Semantic Versioning

Version Format

MAJOR.MINOR.PATCH

MAJOR: Breaking changes
MINOR: New features, backward compatible
PATCH: Bug fixes, backward compatible

Examples:
1.0.0 → 2.0.0 (breaking change)
1.0.0 → 1.1.0 (new feature)
1.0.0 → 1.0.1 (bug fix)

Pre-release Versions

1.0.0-alpha.1    # Alpha release
1.0.0-beta.1     # Beta release
1.0.0-rc.1       # Release candidate

Git Workflow

Branch Strategy

main        → Production-ready code
develop     → Integration branch
feature/*   → New features
bugfix/*    → Bug fixes
release/*   → Release preparation
hotfix/*    → Emergency fixes

Release Branch Flow

# Create release branch
git checkout develop
git checkout -b release/1.2.0

# Prepare release
# - Update version numbers
# - Update changelog
# - Final testing

# Merge to main
git checkout main
git merge release/1.2.0
git tag v1.2.0

# Merge back to develop
git checkout develop
git merge release/1.2.0

Changelog

Keep a Changelog Format

# Changelog

All notable changes to this project will be documented in this file.

## [Unreleased]

## [1.2.0] - 2024-01-15

### Added
- New checkout flow with improved UX
- Support for multiple payment methods

### Changed
- Improved error messages for API responses
- Updated dependencies to latest versions

### Fixed
- Fixed race condition in order processing
- Fixed memory leak in cache service

### Deprecated
- Old checkout endpoint (to be removed in 2.0.0)

### Security
- Fixed XSS vulnerability in user input handling

Automated Changelog

# Using conventional commits
# Format: type(scope): description

feat(checkout): add support for Apple Pay
fix(auth): resolve token refresh issue
docs(api): update API documentation
chore(deps): update dependencies

# Generate changelog from commits
# Use tools like conventional-changelog or release-please

Release Checklist

Pre-Release

pre_release:
  - [ ] All tests passing
  - [ ] Code review completed
  - [ ] Changelog updated
  - [ ] Version bumped
  - [ ] Documentation updated
  - [ ] Breaking changes documented
  - [ ] Migration guide (if needed)
  - [ ] Performance benchmarks run
  - [ ] Security scan passed

Release

release:
  - [ ] Create release branch/tag
  - [ ] Build artifacts
  - [ ] Deploy to staging
  - [ ] Run smoke tests
  - [ ] Deploy to production
  - [ ] Verify deployment
  - [ ] Update status page

Post-Release

post_release:
  - [ ] Monitor metrics
  - [ ] Check error rates
  - [ ] Notify stakeholders
  - [ ] Update issue tracker
  - [ ] Merge back to develop

Hotfix Process

Emergency Fix Flow

# Create hotfix branch from main
git checkout main
git checkout -b hotfix/1.2.1

# Make fix
# Commit with clear message

# Test thoroughly
pytest

# Merge to main and tag
git checkout main
git merge hotfix/1.2.1
git tag v1.2.1

# Merge to develop
git checkout develop
git merge hotfix/1.2.1

Release Automation

GitHub Release Action

name: Release
on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Build
        run: ./build.sh
      
      - name: Create Release
        uses: softprops/action-gh-release@v1
        with:
          files: |
            dist/*.whl
            dist/*.tar.gz
          generate_release_notes: true

Release Please

name: Release Please
on:
  push:
    branches:
      - main

jobs:
  release-please:
    runs-on: ubuntu-latest
    steps:
      - uses: google-github-actions/release-please-action@v4
        with:
          release-type: python

Rollback Strategy

Immediate Rollback

# Kubernetes rollback
kubectl rollout undo deployment/api

# Docker rollback
docker service update --image api:previous-version api

# Feature flag disable
curl -X POST https://feature-flags.internal/disable/new-checkout

Database Rollback

rollback_considerations:
  - Are migrations reversible?
  - Data changes since deployment?
  - Dependent services affected?
  
mitigation:
  - Use feature flags for risky changes
  - Implement backward-compatible migrations
  - Keep old code paths until stable