Release Process

This document explains how BLVM releases are created, what variants are available, version numbering, and how to verify releases.

Overview

BLVM uses an automated release pipeline that builds and releases the entire ecosystem when code is merged to main in any repository. The system uses Cargo’s dependency management to build repositories in the correct order.

Release Triggers

Automatic Release (Push to Main)

The release pipeline automatically triggers when:

A commit is pushed to the main branch in any repository
The commit changes code files (not just documentation)
Paths ignored: **.md, .github/**, docs/**

What happens:

Version is auto-incremented (patch version: X.Y.Z → X.Y.(Z+1))
Dependencies are published to crates.io
All repositories are built in dependency order
Release artifacts are created
GitHub release is created
All repositories are tagged with the version

Manual Release (Workflow Dispatch)

You can manually trigger a release with:

Custom version tag (e.g., v0.2.0)
Platform selection (linux, windows, or both)
Option to skip tagging (for testing)

When to use:

Major or minor version bumps
Coordinated releases
Testing release process

Version Numbering

Automatic Version Bumping

When triggered by a push to main:

Reads current version from blvm/versions.toml (from blvm-consensus version)
Auto-increments the patch version (X.Y.Z → X.Y.(Z+1))
Generates a release set ID (e.g., set-2025-0123)

Manual Version Override

When using workflow dispatch:

Provide a specific version tag (e.g., v0.2.0)
The pipeline uses your provided version instead of auto-incrementing

Semantic Versioning

BLVM uses Semantic Versioning:

MAJOR (X.0.0): Breaking changes
MINOR (0.X.0): New features, backward compatible
PATCH (0.0.X): Bug fixes, backward compatible

Build Process

Dependency Order

The build follows Cargo’s dependency graph:

1. blvm-consensus (no dependencies)
   ↓
2. blvm-protocol (depends on blvm-consensus)
   ↓
3. blvm-node (depends on blvm-protocol + blvm-consensus)
   ↓
4. blvm (depends on blvm-node)

Parallel:
5. blvm-sdk (no dependencies)
   ↓
6. blvm-commons (depends on blvm-sdk)

Build Variants

Each release includes two variants:

Base Variant

Purpose: Stable, production-ready

Features:

Core functionality
Production optimizations
All standard Bitcoin features

Use for: Production deployments

Experimental Variant

Purpose: Full-featured with experimental features

Features: All base features plus:

UTXO commitments
Dandelion++ privacy relay
BIP119 CheckTemplateVerify (CTV)
Stratum V2 mining
BIP158 compact block filters
Signature operations counting
Iroh transport support

Use for: Development, testing, advanced features

Platforms

Both variants are built for:

Linux x86_64 (native)
Windows x86_64 (cross-compiled with MinGW)

Release Artifacts

Binaries Included

Both variants include:

blvm - Bitcoin reference node
blvm-keygen - Key generation tool
blvm-sign - Message signing tool
blvm-verify - Signature verification tool
blvm-commons - Governance application server (Linux only)
key-manager - Key management utility
test-content-hash - Content hash testing tool
test-content-hash-standalone - Standalone content hash test

Archive Formats

Each platform/variant combination produces:

.tar.gz archive (Linux/Unix)
.zip archive (Windows/universal)
SHA256SUMS file for verification

Release Notes

Automatically generated RELEASE_NOTES.md includes:

Release date
Component versions
Build variant descriptions
Installation instructions
Verification instructions

Quality Assurance

Deterministic Build Verification

The pipeline verifies builds are reproducible by:

Building once and saving binary hashes
Cleaning and rebuilding
Comparing hashes (must match exactly)

Note: Non-deterministic builds are warnings (not failures) but should be fixed for production.

Test Execution

All repositories run their test suites:

Unit tests
Integration tests
Library and binary tests
Excluded: Doctests (for Phase 1 speed)

Test Requirements:

All tests must pass
30-minute timeout per repository
Single-threaded execution to avoid resource contention

Git Tagging

Automatic Tagging

When a release succeeds, the pipeline:

Creates git tags in all repositories with the version tag
Tags are annotated with release message
Pushes tags to origin

Repositories Tagged:

blvm-consensus
blvm-protocol
blvm-node
blvm
blvm-sdk
blvm-commons

Tag Format

Format: vX.Y.Z (e.g., v0.1.0)
Semantic versioning
Immutable once created

GitHub Release

Release Creation

The pipeline creates a GitHub release with:

Tag: Version tag (e.g., v0.1.0)
Title: Bitcoin Commons v0.1.0
Body: Generated from RELEASE_NOTES.md
Artifacts: All binary archives and checksums
Type: Official release (not prerelease)

Release Location

Releases are created in the blvm repository as the primary release point for the ecosystem.

Cargo Publishing

Publishing Strategy

To avoid compiling all dependencies when building the final blvm binary, all library dependencies are published to crates.io as part of the release process.

Publishing Order: