From 180f4157369a32c801fbc952ad1fd20dada99f72 Mon Sep 17 00:00:00 2001 From: Dan Albert Date: Tue, 17 Sep 2019 14:01:33 -0700 Subject: [PATCH] Update release instructions (#5933) --- RELEASE.md | 112 +++++++++++++++++++++++++++++++++-------------------- 1 file changed, 71 insertions(+), 41 deletions(-) diff --git a/RELEASE.md b/RELEASE.md index b30210408..8a0df6645 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -59,58 +59,88 @@ There are three release channels that map to branches as follows: * 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 +## Steps to Create a Branch -### Creating a new branch from master - -#### 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 +### Create the new branch +1. Check out the latest commit on `master` branch: + ``` + git fetch --all + git checkout upstream/master + ``` +1. Determine the new branch name. 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 ` +1. Create the new branch and push this branch to the `solana` repository: + ``` + git checkout -b + git push -u origin + ``` -#### Update master with the next version +### Update master branch 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 +1. After the new branch has been created and pushed, update the Cargo.toml files on **master** to the next semantic version (e.g. 0.9.0 -> 0.10.0) with: + ``` + scripts/increment-cargo-version.sh minor + ``` +1. Rebuild to get an updated version of `Cargo.lock`: + ``` + cargo build + ``` +1. Push all the changed Cargo.toml and Cargo.lock files to the `master` branch with something like: + ``` + git co -b version_update + git ls-files -m | xargs git add + git commit -m 'Update Cargo.toml versions from X.Y to X.Y+1' + git push -u origin version_update + ``` +1. Confirm that your freshly cut release branch is shown as `BETA_CHANNEL` and the previous release branch as `STABLE_CHANNEL`: + ``` + ci/channel_info.sh + ``` -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". +## Steps to Create a Release + +### Create the Release Tag on GitHub + +1. Go to [GitHub's Releases UI](https://github.com/solana-labs/solana/releases) for tagging a release. +1. Click "Draft new release". The release tag must exactly match the `version` + field in `/Cargo.toml` prefixed by `v`. + 1. If the Cargo.toml verion field is **0.12.3**, then the release tag must be **v0.12.3** +1. Make sure the Target Branch field matches the branch you want to make a release on. + 1. If you want to release v0.12.0, the target branch must be v0.12 +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). Engineering Lead can provide summary contents for release notes if needed. +1. Click "Save Draft", then confirm the release notes look good and the tag name and branch are correct. Go back into edit the release and click "Publish release" when ready. + +### Update release branch with the next patch version + +1. After the new release has been tagged, update the Cargo.toml files on **release branch** to the next semantic version (e.g. 0.9.0 -> 0.9.1) with: + ``` + scripts/increment-cargo-version.sh patch + ``` +1. Rebuild to get an updated version of `Cargo.lock`: + ``` + cargo build + ``` +1. Push all the changed Cargo.toml and Cargo.lock files to the **release branch** with something like: + ``` + git co -b version_update + git ls-files -m | xargs git add + git commit -m 'Update Cargo.toml versions from X.Y.Z to X.Y.Z+1' + git push -u origin version_update + ``` + +### Verify release automation success +1. Go to [Solana Releases](https://github.com/solana-labs/solana/releases) and click on the latest release that you just published. Verify that all of the build artifacts are present. This can take up to 90 minutes after creating the tag. +1. The `solana-secondary` Buildkite pipeline handles creating the binary tarballs and updated crates. Look for a job under the tag name of the release: https://buildkite.com/solana-labs/solana-secondary +1. [Crates.io](https://crates.io/crates/solana) should have an updated Solana version. ### Update documentation +TODO: Documentation update procedure is WIP as we move to gitbook Document the new recommended version by updating `book/src/running-replicator.md` and `book/src/validator-testnet.md` on the release (beta) branch to point at the `solana-install` for the upcoming release version. -### 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. - -### Publish updated Book +#### Publish updated Book We maintain three copies of the "book" as official documentation: 1) "Book" is the documentation for the latest official release. This should get manually updated whenever a new release is made. It is published here: