Versioning Guide¶

Overview¶

reviewtask follows Semantic Versioning 2.0.0 (SemVer) for all releases. This document describes our versioning rules, release process, and usage guidelines.

Semantic Versioning Rules¶

Version Format: `MAJOR.MINOR.PATCH`¶

Given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes
MINOR version when you add functionality in a backwards compatible manner
PATCH version when you make backwards compatible bug fixes

Version Examples¶

1.0.0 - Initial stable release
1.0.1 - Bug fix release
1.1.0 - New feature release (backwards compatible)
2.0.0 - Breaking change release

When to Bump Each Version Component¶

MAJOR Version (Breaking Changes)¶

Increment when: - Removing or changing existing CLI commands or flags - Changing configuration file format in incompatible ways - Modifying data storage structure requiring migration - Changing behavior that could break existing workflows - Requiring different minimum Go version or dependencies

Examples: - Removing the --old-flag option - Changing .pr-review/config.json schema - Requiring authentication where none was needed before - Changing default behavior of existing commands

MINOR Version (New Features)¶

Increment when: - Adding new CLI commands or subcommands - Adding new configuration options (with backwards compatibility) - Adding new features that don't affect existing functionality - Improving performance significantly - Adding support for new platforms or environments

Examples: - Adding reviewtask export command - Adding new options to existing commands - Supporting new GitHub API features - Adding new AI analysis capabilities - Enhancing output formats

PATCH Version (Bug Fixes)¶

Increment when: - Fixing bugs without changing functionality - Improving error messages or documentation - Updating dependencies for security or stability - Making internal refactoring that doesn't affect behavior - Fixing typos or improving help text

Examples: - Fixing authentication error handling - Correcting task status updates - Improving GitHub API error recovery - Fixing edge cases in task generation

Pre-release and Development Versions¶

Development Versions¶

Use dev for local development builds
Format: 1.2.3-dev or just dev

Pre-release Versions (Future Use)¶

Alpha: 1.2.3-alpha.1 (early testing)
Beta: 1.2.3-beta.1 (feature complete, testing)
Release Candidate: 1.2.3-rc.1 (potential final release)

Version Management Commands¶

Check Current Version¶

# Show version in version command output
./reviewtask version

# Get just the version number
./scripts/version.sh current

# Show detailed version information
./scripts/version.sh info

Bump Version¶

# Increment patch version (1.0.0 → 1.0.1)
./scripts/version.sh bump patch

# Increment minor version (1.0.1 → 1.1.0)
./scripts/version.sh bump minor

# Increment major version (1.1.0 → 2.0.0)
./scripts/version.sh bump major

# Increment based on PR label
./scripts/version.sh bump-from-pr 123

Set Specific Version¶

# Set exact version
./scripts/version.sh set 1.2.3

Release Process¶

Manual Release¶

1. Preparation¶

# Check current state
./scripts/version.sh info

# Prepare release (dry-run and validation)
./scripts/release.sh prepare patch  # or minor/major

2. Create Release¶

# Create actual release
./scripts/release.sh release patch  # or minor/major

Label-based Release (Recommended)¶

1. Add Release Label to PR¶

When creating or reviewing a PR, add one of these labels: - release:major - For breaking changes - release:minor - For new features - release:patch - For bug fixes

2. Automatic Release on Merge¶

When the PR is merged to main: 1. GitHub Actions detects the release label 2. Automatically creates the appropriate version bump 3. Builds and publishes the release 4. Posts a comment on the PR with release details 5. Removes the release label to prevent re-triggering

3. Manual Trigger from PR¶

# Create release based on PR label
./scripts/release.sh release --from-pr 123

# Detect what version would be bumped
./scripts/detect-release-label.sh 123

Automated Process¶

The release process automatically: 1. Validates working directory is clean 2. Detects version bump type from PR label (if using --from-pr) 3. Bumps version using semantic versioning rules 4. Creates git tag (v1.2.3) 5. Builds cross-platform binaries 6. Generates release notes from git commits 7. Creates GitHub release 8. Uploads distribution packages and checksums

Version Sources Priority¶

The version is determined in this order:

Git tags - Exact match for current commit (git describe --tags --exact-match)
Latest git tag - Most recent tag (git describe --tags --abbrev=0)
VERSION file - Local version file in repository root
Default - Falls back to 0.1.0

Git Tag Format¶

Format: vMAJOR.MINOR.PATCH (e.g., v1.2.3)
Prefix: Always use v prefix for git tags
Signing: Tags should be annotated, not lightweight

# Correct tag creation (done automatically by scripts)
git tag -a v1.2.3 -m "Release v1.2.3"

# Incorrect (don't do this manually)
git tag 1.2.3  # missing 'v' prefix
git tag v1.2.3  # lightweight tag

Binary Version Embedding¶

Build-time Variables¶

Versions are embedded in binaries using Go's -ldflags:

go build -ldflags="
  -X main.version=1.2.3
  -X main.commitHash=abc1234
  -X main.buildDate=2023-12-01T10:00:00Z
" -o reviewtask .

Version Information Display¶

$ ./reviewtask version
reviewtask version 1.2.3
Commit: abc1234
Built: 2023-12-01T10:00:00Z
Go version: go1.21.0
OS/Arch: linux/amd64

Release Naming and Documentation¶

Release Names¶

Use simple descriptive names: Release v1.2.3
Avoid creative codenames for consistency

Release Notes Structure¶

# Release v1.2.3

## Changes
- Feature: Add new task export functionality
- Fix: Resolve authentication timeout issues
- Improvement: Enhance error message clarity

## Installation
[Installation instructions]

## Verification
[Checksum verification instructions]

Compatibility Policy¶

Backwards Compatibility¶

MINOR and PATCH versions: Always backwards compatible
MAJOR versions: May introduce breaking changes
Configuration: Provide migration guides for breaking changes
Data: Maintain data format compatibility within major versions

Deprecation Policy¶

Deprecation Notice: Announce in MINOR release
Deprecation Period: Minimum 1 major version
Removal: Only in next MAJOR release

Example: - v1.5.0: Deprecate --old-flag (show warning) - v1.6.0-v1.x.x: Continue supporting with warnings - v2.0.0: Remove --old-flag completely

Version Validation¶

Automated Checks¶

Version format validation in scripts
Build verification for all target platforms
GitHub Actions workflow validation
Cross-compilation testing

Manual Verification¶

# Test version operations
./scripts/test_versioning.sh

# Verify cross-platform builds
./scripts/build.sh test

# Check GitHub Actions workflow
gh workflow run release.yml --ref v1.2.3

Best Practices¶

For Developers¶

Always use scripts for version management
Never manually edit version numbers in code
Test cross-compilation before releases
Document breaking changes clearly
Follow commit message conventions for release notes

For Contributors¶

Consider version impact of changes
Document breaking changes in PR descriptions
Test version embedding in builds
Verify backwards compatibility

For Users¶

Pin to specific versions in production
Test new versions in development first
Read release notes for breaking changes
Verify checksums for downloaded binaries

Troubleshooting¶

Common Issues¶

Version shows as "dev"

# Cause: No git tags or VERSION file
# Solution: Create initial tag or VERSION file
echo "1.0.0" > VERSION
git tag v1.0.0

Version bump fails

# Cause: Uncommitted changes
# Solution: Commit or stash changes first
git status
git add .
git commit -m "Prepare for release"

Cross-compilation fails

# Cause: Missing dependencies or invalid GOOS/GOARCH
# Solution: Test individual platforms
GOOS=linux GOARCH=amd64 go build .

Getting Help¶

Check version info: ./scripts/version.sh info
Test build process: ./scripts/build.sh test
Prepare release: ./scripts/release.sh prepare
Report issues: GitHub Issues