Skip to content

RELEASE_GUIDE.md

Latest commit

 

History

History
95 lines (67 loc) · 3.48 KB

RELEASE_GUIDE.md

File metadata and controls

95 lines (67 loc) · 3.48 KB

Release Guide (stable-structures)

This guide describes how to cut releases and publish them to crates.io for ic-stable-structures.

Goals

  • Ship improvements without breaking users
  • Validate APIs and memory model before stabilization
  • Keep rollback cheap

Release Options

  • Opt-in feature flags
    Hide experimental code behind non-default flags.

  • Semantic Versioning Pre-Releases (semver.org)

    • x.y.z-alpha.N — experimental, incomplete, may be unstable or buggy
    • x.y.z-beta.N — feature complete, testing needed, bugs expected
    • x.y.z-rc.N — release candidate, no new features, only bug fixes

Cargo won’t auto-pick pre-releases; users must pin them explicitly.

Policy

  • Any breaking and/or major change requires a design doc reviewed by stakeholders before release.
  • Pre-releases (-alpha, -beta, -rc) are strongly encouraged for high-risk changes.

When to Use (stable-structures specific)

  • Public API changes

    • Added methods → behind a feature flag until validated
    • Removed/signature changes → breaking (minor bump <1.0.0, major bump ≥1.0.0)

  • Stable memory layout changes

    • New/altered layout → feature flag + pre-release
    • Layout-breaking (cannot read old data) → breaking (minor bump <1.0.0, major bump ≥1.0.0)

  • Processing-only changes (no layout change)

    • Compatible algorithmic updates → minor bump
    • High risk → feature flag and/or pre-release
    • Examples
      • Changing default values, coercions, or type conversions
      • Altering validation rules
      • Updating how parsing, ordering, deduplication, or filtering logic is applied
      • Modifying error handling or recovery behavior when reading/writing to stable memory

  • Hidden layout migrations (auto-migrate on load)

    • If old data won’t load without migration → treat as breaking
    • Ship via feature flag + pre-releases; promote only after successful trials

Example: Memory Reclaim

Adding a reclaim() method to free unused memory without changing layout, only processing it differently, is high risk and may cause data corruption:

  • Hide reclaim() behind a feature flag
  • High risk → release as -beta.N
  • Iterate with feedback, promote to stable once validated
  • Remove feature flag after stabilization

Release Process

Prepare

  1. Bump version in Cargo.toml:

    [package]
version = "x.y.z"

  2. Ensure CI is green.

  3. Preferable commit & PR name: chore(release): vX.Y.Z (example PR).

Publish Release to GitHub

  1. Identify the commit to release.
  2. Draft a new release:
    • Go to the Releases tab.
    • Click Draft a new release.
    • Create a new tag vX.Y.Z pointing to the commit.
    • Set the release title to vX.Y.Z.
    • Choose the previous tag as the last release.
    • Add release notes (GitHub can auto-generate, adjust as needed).
  3. Click Publish release.

Publish to crates.io

  1. On the repository main page, navigate to the Actions tab.
  2. Click on the workflow to publish to crates.io
  3. Click on run workflow and select the version tag created above for the workflow to run on.

Verify