Skip to content

RELEASE.md

Latest commit

 

History

History
216 lines (153 loc) · 4.46 KB

RELEASE.md

File metadata and controls

216 lines (153 loc) · 4.46 KB
Raw

Release Workflow

This document outlines the release process and versioning policy for rjapi.

Semantic Versioning (SemVer)

This project follows Semantic Versioning 2.0.0. 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

Pre-release Versions

Pre-release versions follow the format: MAJOR.MINOR.PATCH-IDENTIFIER.NUMBER

  • 0.1.0-alpha.1 - Alpha releases for early testing
  • 0.1.0-beta.1 - Beta releases for wider testing
  • 0.1.0-rc.1 - Release candidates for final testing

Release Types

Major Releases (Breaking Changes)

Examples of breaking changes:

  • Removing or renaming public APIs
  • Changing function signatures
  • Modifying behavior that could break existing code
  • Changing minimum supported Rust version (MSRV)
  • Removing features

Minor Releases (New Features)

Examples of minor changes:

  • Adding new public APIs
  • Adding new optional features
  • Deprecating APIs (with backwards compatibility)
  • Performance improvements
  • New examples or documentation

Patch Releases (Bug Fixes)

Examples of patch changes:

  • Bug fixes that don't change API
  • Documentation improvements
  • Internal refactoring
  • Dependency updates (if not breaking)

Release Process

1. Pre-release Checks

Before releasing, ensure all checks pass:

# Format code
cargo fmt --all

# Run lints
cargo clippy --all-targets --all-features -- -D warnings

# Run all tests
cargo test --all-features

# Check documentation
cargo doc --no-deps --all-features

# Verify examples work
cargo run --example basic
cargo run --example error_handling

# Dry run publish
cargo publish --dry-run

2. Update Version

Update version in Cargo.toml:

[package]
version = "x.y.z"  # New version number

3. Update Changelog

Maintain CHANGELOG.md following Keep a Changelog:

## [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

4. Commit and Tag

# Commit version bump
git add .
git commit -m "Release v0.0.2"

# Create and push tag
git tag v0.0.2
git push origin main --tags

5. Publish to Crates.io

# Login to crates.io (first time only)
cargo login

# Publish
cargo publish

6. Post-release

  • Update GitHub release notes
  • Announce on relevant forums/social media
  • Update documentation if needed

Automated Release (Optional)

Consider using cargo-release for automation:

# Install cargo-release
cargo install cargo-release

# Perform release (patch version)
cargo release patch

# Perform release (minor version)
cargo release minor

# Perform release (major version)
cargo release major

Yanking Releases

If a release has critical issues:

# Yank a problematic version
cargo yank --vers 0.1.0

# Un-yank if the issue was resolved
cargo yank --vers 0.1.0 --undo

MSRV (Minimum Supported Rust Version)

Current MSRV: 1.85.0 (required for Edition 2024)

MSRV changes are considered breaking changes and require a major version bump, except:

  • During 0.x versions where minor version bumps are acceptable
  • When the new MSRV is required for security updates

Branch Strategy

  • main - Latest stable code
  • Feature branches for new development
  • Release tags for specific versions

Testing Strategy

All releases must pass:

  • Unit tests
  • Integration tests
  • Documentation tests
  • Examples compilation
  • Clippy lints
  • Format checks
  • MSRV compatibility

Deprecation Policy

When deprecating features:

  1. Mark as deprecated with #[deprecated] attribute
  2. Provide migration path in documentation
  3. Keep deprecated features for at least one major version
  4. Remove in next major version

Example:

#[deprecated(since = "0.2.0", note = "Use `new_function` instead")]
pub fn old_function() {
    // Implementation
}

Security Updates

Security fixes take priority and may be backported to previous versions if needed.

Emergency Releases

For critical bugs or security issues:

  1. Create hotfix branch from affected version tag
  2. Apply minimal fix
  3. Release patch version immediately
  4. Backport to main branch if needed