# Solana Release process ## Branches and Tags ``` ========================= master branch (edge channel) =======================> \ \ \ \___v0.7.0 tag \ \ \ \ v0.9.0 tag__\ \ v0.8.0 tag__\ \ v0.7.1 tag__\ \ v0.9 branch (beta channel) \___v0.7.2 tag \___v0.8.1 tag \ \ \ \ v0.7 branch v0.8 branch (stable channel) ``` ### master branch All new development occurs on the `master` branch. Bug fixes that affect a `vX.Y` branch are first made on `master`. This is to allow a fix some soak time on `master` before it is applied to one or more stabilization branches. Merging to `master` first also helps ensure that fixes applied to one release are present for future releases. (Sometimes the joy of landing a critical release blocker in a branch causes you to forget to propagate back to `master`!)" Once the bug fix lands on `master` it is cherry-picked into the `vX.Y` branch and potentially the `vX.Y-1` branch. The exception to this rule is when a bug fix for `vX.Y` doesn't apply to `master` or `vX.Y-1`. Immediately after a new stabilization branch is forged, the `Cargo.toml` minor version (*Y*) in the `master` branch is incremented by the release engineer. Incrementing the major version of the `master` branch is outside the scope of this document. ### v*X.Y* stabilization branches These are stabilization branches for a given milestone. They are created off the `master` branch as late as possible prior to the milestone release. ### v*X.Y.Z* release tag The release tags are created as desired by the owner of the given stabilization branch, and cause that *X.Y.Z* release to be shipped to https://crates.io Immediately after a new v*X.Y.Z* branch tag has been created, the `Cargo.toml` patch version number (*Z*) of the stabilization branch is incremented by the release engineer. ## Channels Channels are used by end-users (humans and bots) to consume the branches described in the previous section, so they may automatically update to the most recent version matching their desired stability. There are three release channels that map to branches as follows: * edge - tracks the `master` branch, least stable. * beta - tracks the largest (and latest) `vX.Y` stabilization branch, more stable. * stable - tracks the second largest `vX.Y` stabilization branch, most stable. ## Release Steps ### Advance the Channels #### Create the new branch 1. Pick your branch point for release on master. 1. Create the branch. The name should be "v" + the first 2 "version" fields from Cargo.toml. For example, a Cargo.toml with version = "0.9.0" implies the next branch name is "v0.9". 1. Note the Cargo.toml in the repo root directory does not contain a version. Look at any other Cargo.toml file. 1. Create a new branch and push this branch to the solana repository. 1. `git checkout -b ` 1. `git push -u origin ` #### Update master with the next version 1. After the new branch has been created and pushed, update Cargo.toml on **master** to the next semantic version (e.g. 0.9.0 -> 0.10.0) by running `./scripts/increment-cargo-version.sh`, then rebuild with `cargo build` to cause a refresh of `Cargo.lock`. 1. Push your Cargo.toml change and the autogenerated Cargo.lock changes to the master branch At this point, `ci/channel-info.sh` should show your freshly cut release branch as "BETA_CHANNEL" and the previous release branch as "STABLE_CHANNEL". ### Make the Release We use [github's Releases UI](https://github.com/solana-labs/solana/releases) for tagging a release. 1. Go [there ;)](https://github.com/solana-labs/solana/releases). 1. Click "Draft new release". The release tag must exactly match the `version` field in `/Cargo.toml` prefixed by `v` (ie, `.X`). 1. If the Cargo.toml verion field is **0.12.3**, then the release tag must be **v0.12.3** 1. If this is the first release on the branch (e.g. v0.13.**0**), paste in [this template](https://raw.githubusercontent.com/solana-labs/solana/master/.github/RELEASE_TEMPLATE.md) and fill it in. 1. Test the release by generating a tag using semver's rules. First try at a release should be `.X-rc.0`. 1. Verify release automation: 1. [Crates.io](https://crates.io/crates/solana) should have an updated Solana version. 1. Once the release has been made, update Cargo.toml on the release branch to the next semantic version (e.g. 0.9.0 -> 0.9.1) by running `./scripts/increment-cargo-version.sh patch`, then rebuild with `cargo build` to cause a refresh of `Cargo.lock`. 1. Push your Cargo.toml change and the autogenerated Cargo.lock changes to the release branch. ### Update software on testnet.solana.com The testnet running on testnet.solana.com is set to use a fixed release tag which is set in the Buildkite testnet-management pipeline. This tag needs to be updated and the testnet restarted after a new release tag is created. #### Update testnet schedules Go to https://buildkite.com/solana-labs and click through: Pipelines -> testnet-management -> Pipeline Settings -> Schedules Or just click here: https://buildkite.com/solana-labs/testnet-management/settings/schedules There are two scheduled jobs for testnet: a daily restart and an hourly sanity-or-restart. \ https://buildkite.com/solana-labs/testnet-management/settings/schedules/0efd7856-7143-4713-8817-47e6bdb05387 https://buildkite.com/solana-labs/testnet-management/settings/schedules/2a926646-d972-42b5-aeb9-bb6759592a53 On each schedule: 1. Set TESTNET_TAG environment variable to the desired release tag. 1. Example, TESTNET_TAG=v0.13.2 1. Set the Build Branch to the branch that TESTNET_TAG is from. 1. Example: v0.13 #### Restart the testnet Trigger a TESTNET_OP=create-and-start to refresh the cluster with the new version 1. Go to https://buildkite.com/solana-labs/testnet-management 2. Click "New Build" and use the following settings, then click "Create Build" 1. Commit: HEAD 1. Branch: [channel branch as set in the schedules] 1. Environment Variables: ``` TESTNET=testnet TESTNET_TAG=[same value as used in TESTNET_TAG in the schedules] TESTNET_OP=create-and-start ``` #### Update documentation Document the new recommended version by updating ```export SOLANA_RELEASE=[new scheduled TESTNET_TAG value]``` in book/src/testnet-participation.md for both edge and beta channel branches. ### Alert the community Notify Discord users on #validator-support that a new release for testnet.solana.com is available