Skip to content

Latest commit

 

History

History
99 lines (66 loc) · 6.34 KB

release-process.md

File metadata and controls

99 lines (66 loc) · 6.34 KB
Raw

Release Process

Platform support

Platform Supported
Linux 64-bit ✅
MacOS 64-bit ✅
Windows 64-bit ✅
MacOS Apple Silicon (ARM64) builds are provided but not tested
Linux ARMv7 builds are provided but not tested
Linux ARM64 builds are provided but not tested

Release Schedule and Hotfixes

Normal releases in this repository that add new features are released on a monthly schedule. The currently staged changes for such releases are in the develop branch. It is generally safe to run a stacks-node from that branch, though it has received less rigorous testing than release tags or the master branch. If bugs are found in the develop branch, please do report them as issues on this repository.

For fixes that impact the correct functioning or liveness of the network, hotfixes may be issued. These are patches to the main branch which are backported to the develop branch after merging. These hotfixes are categorized by priority according to the following rubric:

  • High Priority. Any fix for an issue that could deny service to the network as a whole, e.g., an issue where a particular kind of invalid transaction would cause nodes to stop processing requests or shut down unintentionally. Any fix for an issue that could cause honest miners to produce invalid blocks.
  • Medium Priority. Any fix for an issue that could cause miners to waste funds.
  • Low Priority. Any fix for an issue that could deny service to individual nodes.

Versioning

This repository uses a 5 part version number:

X.Y.Z.A.n

X major version - in practice, this does not change unless there’s another significant network update (e.g. a Stacks 3.0 type of event)
Y increments on consensus-breaking changes
Z increments on non-consensus-breaking changes that require a fresh chainstate (akin to semantic MAJOR)
A increments on non-consensus-breaking changes that do not require a fresh chainstate, but introduce new features (akin to semantic MINOR)
n increments on patches and hot-fixes (akin to semantic PATCH)

Optionally, an extra pre-release field may be appended to the version to specify a release candidate in the format -rc[0-9].

Non-Consensus Breaking Release Process

The release must be timed so that it does not interfere with a prepare phase. The timing of the next Stacking cycle can be found here; to avoid interfering with the prepare phase, all releases should happen at least 24 hours before the start of a new cycle.

  1. Before creating the release, the version number must be determined, where the factors that determine the version number are discussed in Versioning.

    • First determine whether there are any "non-consensus-breaking changes that require a fresh chainstate".
      • In other words, the database schema has changed, but an automatic migration was not implemented.
      • Determine whether this a feature release, as opposed to a hotfix or a patch.
    • A new branch in the format release/X.Y.Z.A.n(-rc[0-9]) is created from the base branch develop.

  2. Enumerate PRs and/or issues that would block the release.

    • A label should be applied to each such issue/PR as X.Y.Z.A.n-blocker.

  3. Since development is continuing in the develop branch, it may be necessary to cherry-pick some commits into the release branch.

    • Create a feature branch from release/X.Y.Z.A.n, ex: feat/X.Y.Z.A.n-pr_number.
    • Add cherry-picked commits to the feat/X.Y.Z.A.n-pr_number branch
    • Merge feat/X.Y.Z.A.n-pr_number into release/X.Y.Z.A.n.

  4. Open a PR to update the CHANGELOG file in the release/X.Y.Z.A.n branch.

    • Create a chore branch from release/X.Y.Z.A.n, ex: chore/X.Y.Z.A.n-changelog.

    • Add summaries of all Pull Requests to the Added, Changed and Fixed sections.

      • Pull requests merged into develop can be found here.

        Note: GitHub does not allow sorting by merge time, so, when sorting by some proxy criterion, some care should be used to understand which PR's were merged after the last release.

  5. Once chore/X.Y.Z.A.n-changelog has merged, a build may be started by manually triggering the CI workflow against the release/X.Y.Z.A.n branch.

  6. Once the release candidate has been built and binaries are available, ecosystem participants shall be notified to test the tagged release on various staging infrastructure.

  7. The release candidate will test that it successfully syncs with the current chain from genesis both in testnet and mainnet.

  8. If bugs or issues emerge from the rollout on staging infrastructure, the release will be delayed until those regressions are resolved.

    • As regressions are resolved, additional release candidates should be tagged.
    • Repeat steps 3-7 as necessary.

  9. Once the final release candidate has rolled out successfully without issue on staging infrastructure, the tagged release shall no longer marked as Pre-Release on the Github releases page. Announcements will then be shared in the #stacks-core-devs channel in the Stacks Discord, as well as the mailing list.

  10. Finally, the following merges will happen to complete the release process:

    • Release branch release/X.Y.Z.A.n will be merged into the master branch.
    • Then, master will be merged into develop.

Consensus Breaking Release Process

Consensus breaking releases shall follow the same overall process as a non-consensus release, with the following considerations:

  • The release must be timed so that sufficient time is given to perform a genesis sync.
  • The release must take into account the activation height at which the new consensus rules will take effect.