Release Process

Release Process

Overview

This document defines the release process for HeliosDB Nano, including versioning, release types, and procedures.

Versioning

HeliosDB Nano follows Semantic Versioning 2.0.0:

MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]

Component	When to Increment
MAJOR	Breaking changes, incompatible API changes
MINOR	New features, backward-compatible
PATCH	Bug fixes, backward-compatible
PRERELEASE	alpha, beta, rc (e.g., 4.0.0-beta.1)

Version Examples

• 3.5.8 - Stable release
• 3.5.9 - Patch with bug fixes
• 3.6.0 - Minor with new features
• 4.0.0 - Major with breaking changes
• 4.0.0-alpha.1 - Pre-release
• 4.0.0-rc.1 - Release candidate

Release Types

Patch Release (x.x.PATCH)

Frequency: As needed Content: Bug fixes, security patches, documentation Breaking Changes: None

Process:

1. Create branch from latest release tag
2. Cherry-pick fixes
3. Update CHANGELOG.md
4. Create release PR
5. Core Team approval (1 member)
6. Tag and release

Minor Release (x.MINOR.0)

Frequency: Monthly (approximately) Content: New features, enhancements, deprecations Breaking Changes: None (deprecations announced)

Process:

1. Feature freeze (1 week before release)
2. Release branch created from main
3. Bug fix period
4. Release candidate (optional)
5. Update CHANGELOG.md
6. Core Team approval (consensus)
7. Tag and release

Major Release (MAJOR.0.0)

Frequency: Annually (approximately) Content: Breaking changes, major features, removals Breaking Changes: Yes (documented migration path)

Process:

1. RFC for major changes
2. Deprecation warnings in prior minor releases
3. Feature freeze (2 weeks before release)
4. Beta releases
5. Release candidate(s)
6. Migration guide published
7. Core Team + BDFL approval
8. Tag and release

Release Schedule

Week 1: Feature Development
Week 2: Feature Development
Week 3: Feature Freeze (bug fixes only)
Week 4: Release Candidate → Release

Calendar (2026)

Release	Type	Target Date	Status
3.5.9	Patch	2026-01-31	Planning
3.6.0	Minor	2026-02-28	Planning
3.8.0	Minor	2026-03-31	Planning
4.0.0	Major	2026-06-30	Planning

Release Checklist

Pre-Release

• All planned issues closed or moved
• All tests passing on main
• Security scan clean (cargo-audit)
• Dependencies updated
• Documentation updated
• CHANGELOG.md updated
• Version bumped in Cargo.toml
• Release notes drafted

Release Day

• Create release branch (if minor/major)
• Final CI/CD run passes
• Tag created: git tag -a v3.5.9 -m "Release v3.5.9"
• Tag pushed: git push origin v3.5.9
• GitHub release created with notes
• Binaries built and attached
• crates.io published
• Docker images pushed
• Homebrew formula updated
• Website updated

Post-Release

• Announcement posted (blog, Twitter, Discord)
• Release notes sent to mailing list
• Version incremented to next dev version
• Release retrospective (if major)

Release Commands

Tagging

# Ensure clean state
git checkout main
git pull origin main
git status  # Should be clean

# Update version
# Edit Cargo.toml: version = "3.5.9"
# Edit CHANGELOG.md

# Commit version bump
git add Cargo.toml CHANGELOG.md
git commit -m "chore: bump version to 3.5.9"

# Create annotated tag
git tag -a v3.5.9 -m "Release v3.5.9

Highlights:
- Bug fix for XYZ
- Security patch for ABC

See CHANGELOG.md for full details."

# Push
git push origin main
git push origin v3.5.9

GitHub Release

# Create release with notes
gh release create v3.5.9 \
  --title "HeliosDB Nano v3.5.9" \
  --notes-file RELEASE_NOTES.md

# Attach binaries
gh release upload v3.5.9 \
  target/release/heliosdb-nano-linux-amd64 \
  target/release/heliosdb-nano-darwin-amd64 \
  target/release/heliosdb-nano-windows-amd64.exe

crates.io

# Verify package
cargo package --list

# Publish
cargo publish

Docker

# Build multi-platform images
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --tag heliosdb/heliosdb-nano:3.5.9 \
  --tag heliosdb/heliosdb-nano:latest \
  --push .

CHANGELOG Format

# Changelog

## [3.5.9] - 2026-01-31

### Security
- Fixed CVE-XXXX-YYYY: Description

### Fixed
- Fixed issue with XYZ (#123)
- Resolved ABC problem (#456)

### Changed
- Updated dependency X to v2.0

## [3.5.8] - 2026-01-15

### Added
- New feature: Description (#100)

### Fixed
- Fixed bug in... (#101)

### Deprecated
- Deprecated old_function(), use new_function() instead

Hotfix Process

For critical bugs or security issues in released versions:

# 1. Create hotfix branch from release tag
git checkout -b hotfix/3.5.8-cve v3.5.8

# 2. Apply fix
git cherry-pick <fix-commit>
# OR create fix directly

# 3. Update version and changelog
# Edit Cargo.toml: 3.5.8 → 3.5.9

# 4. Tag hotfix release
git tag -a v3.5.9 -m "Hotfix: CVE-XXXX-YYYY"
git push origin v3.5.9

# 5. Merge fix to main
git checkout main
git cherry-pick <fix-commit>
git push origin main

Support Policy

Version	Support Status	End of Life
3.x (current)	Active	6 months after 4.0
2.x	Security only	2026-06-30
1.x	EOL	Ended

Support Types

• Active: Bug fixes, security patches, features
• Security Only: Critical security patches only
• EOL: No support, upgrade required

Release Roles

Role	Responsibility	Current
Release Manager	Coordinates release	Rotating
QA Lead	Final testing sign-off	[Name]
Docs Lead	Documentation updates	[Name]
Comms Lead	Announcements	[Name]

Rollback Procedure

If a release has critical issues:

1. Assess: Determine severity and scope
2. Communicate: Post status update immediately
3. Decide: Hotfix forward or rollback
4. Rollback (if needed):

   # Mark release as pre-release (hides from latest)
   gh release edit v3.5.9 --prerelease
   
   # Or delete release entirely
   gh release delete v3.5.9
   git push --delete origin v3.5.9

5. Fix: Apply fix via hotfix process
6. Post-mortem: Document what happened and how to prevent