Skip to content

RELEASING.md

Latest commit

 

History

History
213 lines (163 loc) · 8.48 KB

RELEASING.md

File metadata and controls

213 lines (163 loc) · 8.48 KB
Raw

Releasing sc-compose

Step-by-step release process for sc-sha, sc-composer, sc-compose, bindings/sc-sha-python, and bindings/python from this repo.

Overview

This repo publishes to six channels:

Channel Package Method
crates.io sc-sha cargo publish
crates.io sc-composer cargo publish
crates.io sc-compose cargo publish
PyPI sc-sha, sc-compose maturin publish
Homebrew sc-compose GitHub Actions → randlee/homebrew-tap
Winget sc-compose GitHub Actions → microsoft/winget-pkgs
Scoop sc-compose GitHub Actions → randlee/scoop-bucket
GitHub Releases sc-compose CI workflow attachment

Versioning

  • Single workspace version for all crates in this repo.
  • bindings/sc-sha-python/pyproject.toml and bindings/python/pyproject.toml must sync from the workspace version before wheel builds. The release workflow enforces this via verify-python-version.
  • Target version must be strictly higher than the last published version on crates.io for these crate names.

Pre-Release Checklist

Version Alignment

  • Workspace Cargo.toml [workspace.package] version reflects the target version
  • crates/sc-sha/Cargo.toml matches or inherits workspace version
  • crates/sc-composer/Cargo.toml matches or inherits workspace version
  • crates/sc-compose/Cargo.toml matches or inherits workspace version
  • release/publish-artifacts.toml lists all publishable crates with correct paths
  • bindings/sc-sha-python/pyproject.toml version matches workspace version
  • bindings/python/pyproject.toml version matches workspace version

Quality Gates

  • cargo test --workspace — zero failures
  • cargo clippy --all-targets --all-features -- -D warnings — clean
  • cargo fmt --all --check — clean
  • just lint && just test && just smoke — all pass
  • just reports && just reports-verify — report pipeline intact
  • observability-health and sc-observability shutdown behavior covered by tests
  • ERR_* failure-mode matrix exercised by tests
  • --json commands verified to keep stdout machine-readable
  • Standalone boundary verification: no forbidden ATM references in source
  • quality-mgr full QA pass
  • team-lead final design review

crates.io Ownership

  • cargo owner --list sc-sha — confirm expected owners
  • cargo owner --list sc-composer — confirm expected owners
  • cargo owner --list sc-compose — confirm expected owners
  • CARGO_REGISTRY_TOKEN configured in GitHub Actions crates-io environment
  • Token has publish permission for sc-sha, sc-composer, and sc-compose

Homebrew, Winget, and Scoop

  • HOMEBREW_TAP_TOKEN configured in repo secrets
  • WINGET_GITHUB_TOKEN configured in repo secrets with permission to open Winget submissions in microsoft/winget-pkgs; every release dispatches the automated winget-publish.yml workflow
  • SCOOP_BUCKET_TOKEN configured in repo secrets with write access to randlee/scoop-bucket

PyPI

  • PYPI_API_TOKEN and TEST_PYPI_API_TOKEN configured in GitHub Actions environments
  • Run one staged TestPyPI or workflow_dispatch rehearsal before treating the Python release channel as production-closed:
    • Both packages build wheels on all three platforms
    • Exactly one sdist is produced for each package
    • PyPI upload paths succeed for both packages
    • GitHub Release attachment set includes both packages' wheels + sdists

Release Preflight

  • Trigger .github/workflows/release-preflight.yml (manual via gh workflow run release-preflight.yml)
  • Preflight must PASS: version alignment, manifest completeness, workspace consistency

Publish Order (MANDATORY)

Publish in this exact order. Deviating will break the dependency graph.

  1. sc-sha — publish first
    • cargo publish -p sc-sha
    • Wait ≥30 seconds for crates.io index propagation
  2. sc-composer — publish after sc-sha
    • cargo publish -p sc-composer
    • Wait ≥30 seconds for crates.io index propagation
  3. sc-compose — publish after its library dependencies
    • cargo publish -p sc-compose

The manually dispatched .github/workflows/release.yml workflow creates the production tag in its gate-and-tag job, then enforces this order automatically.

Post-Release Channel Dispatch

After the root Release workflow has created the immutable GitHub Release, dispatch the independent, retry-safe channel workflows with the same v<version> tag:

  • .github/workflows/pypi-publish.yml uploads the published Python artifacts.
  • .github/workflows/homebrew-publish.yml updates randlee/homebrew-tap.
  • .github/workflows/winget-publish.yml submits the Windows installer.
  • .github/workflows/scoop-publish.yml updates the Scoop bucket manifest in randlee/scoop-bucket.

If one channel fails, re-dispatch only that channel workflow. Do not recreate the tag or rerun the root release workflow.

Post-Publish Verification

  • Verify sc-sha visible on crates.io at expected version
  • Verify sc-composer visible on crates.io at expected version
  • Verify sc-compose visible on crates.io at expected version
  • cargo add sc-sha@<version> in a scratch workspace — resolves cleanly
  • cargo add sc-composer@<version> in a scratch workspace — resolves cleanly
  • cargo install sc-compose@<version> — binary installs cleanly
  • Verify GitHub Release archives include share/sc-compose/examples/
  • Verify Homebrew formula update completed in randlee/homebrew-tap
  • Verify winget submission/update dispatched successfully
  • Verify Scoop manifest update completed in randlee/scoop-bucket and scoop install sc-compose succeeds
  • Verify PyPI: pip install sc-sha==<version> sc-compose==<version> on all three platforms
  • Confirm the production gate-and-tag job created v<version> at origin/main
  • Confirm the release workflow created the GitHub Release for that tag with its generated release notes

Distribution Channel Details

crates.io

  • Manifest: release/publish-artifacts.toml
  • Preflight: .github/workflows/release-preflight.yml
  • Release: .github/workflows/release.yml
  • Gate helper: .github/scripts/release_artifacts.py (invoked by the vendored plugins/sc-publish release workflows)

PyPI

  • Pre-release rehearsals go to TestPyPI: 
    pip install -i https://test.pypi.org/simple/ sc-sha sc-compose
  • Production releases for sc-sha and sc-compose go to PyPI via the pypi protected environment
  • verify-python-version gate enforces version sync for both Python packages before wheel builds

Homebrew

  • Formula auto-updated in randlee/homebrew-tap via release workflow
  • Bundled examples installed to $(brew --prefix)/share/sc-compose/examples/

Scoop

  • Add the bucket, then install the package: 
    scoop bucket add randlee https://github.com/randlee/scoop-bucket
scoop install sc-compose
  • The retry-safe .github/workflows/scoop-publish.yml workflow updates the manifest from the immutable GitHub Release asset.

GitHub Releases

  • Archives include bin/sc-compose and share/sc-compose/examples/...
  • Platform-specific archives: Linux, macOS, Windows

Cargo Install Limitation

cargo install ships the binary only — it does NOT install bundled examples. Users who install with Cargo must set SC_COMPOSE_DATA_DIR to access examples.

Release Notes

Fill out release/RELEASE-NOTES-TEMPLATE.md with the actual release summary before creating the GitHub release. The template covers:

  • Summary of changes
  • Included crates and versions
  • Compatibility notes and migration guidance

ATM Cutover

When the ATM workspace needs to switch from in-workspace path dependencies to crates.io dependencies from this repo:

  1. This repo must publish the target version of sc-sha
  2. This repo must publish the target version of sc-composer
  3. This repo must publish the target version of sc-compose
  4. ATM must replace its in-workspace path dependencies with version pins

Reference Documents