Release Process¶

This document describes the release workflow for ASAM OSI Utilities.

Versioning¶

The project follows Semantic Versioning:

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

Pre-release Versions¶

Pre-release versions use suffixes:

X.Y.Z-alpha.N — Early development, unstable
X.Y.Z-beta.N — Feature complete, testing phase
X.Y.Z-rc.N — Release candidate, final testing

Examples: 1.0.0-alpha.1, 1.0.0-beta.2, 1.0.0-rc.1

Version Sources¶

The canonical version is stored in:

vcpkg.json → version-string field

Release Workflow¶

1. Prepare the Release¶

Ensure all changes for the release are merged to main:

git checkout main
git pull --recurse-submodules

2. Update Version¶

Update the version in vcpkg.json:

{
  "version-string": "1.0.0"
}

Commit the version bump:

git commit -S -s -m "chore: bump version to 1.0.0"
git push origin main

3. Trigger the Release¶

Go to Actions → Release workflow
Click Run workflow
The version will be read automatically from vcpkg.json
Select pre-release option if applicable
Click Run workflow

The workflow will:

Validate the version format
Run full CI checks (format, lint, build, test)
Build release artifacts for all platforms
Generate changelog from conventional commits
Create a Git tag
Create a GitHub Release with artifacts

4. Post-Release¶

After a successful release:

Verify the GitHub Release page
Verify artifacts are attached and downloadable
Announce the release if needed

Release Artifacts¶

Each release includes pre-built binaries for:

Platform	Archive Format	Contents
Ubuntu (x64)	`.tar.gz`	Static library, headers, cmake
macOS (x64)	`.tar.gz`	Static library, headers, cmake
macOS (arm64)	`.tar.gz`	Static library, headers, cmake
Windows (x64)	`.zip`	Static library, headers, cmake

Additionally:

Source archive (auto-generated by GitHub)
Changelog (in release notes)

Changelog Generation¶

Changelogs are auto-generated from conventional commit messages since the last release:

feat: → Features
fix: → Bug Fixes
perf: → Performance Improvements
docs: → Documentation (if significant)
refactor: → Code Refactoring (if significant)

Breaking changes (commits with BREAKING CHANGE: in body or ! after type) are highlighted separately.

Hotfix Releases¶

For critical fixes to older releases:

Create a branch from the release tag: git checkout -b hotfix/1.0.1 v1.0.0
Apply the fix and commit
Update version to 1.0.1
Push the branch and create a PR to main (for the fix)
Trigger the release workflow from the hotfix branch