Maintaining

Overview

We use a three-stage release pipeline. Each stage of the release pipeline has its own dedicated branch and a corresponding "train" (also called a pace). Features and bug fixes progress through each stage--and are subject to testing along the way--until they're eventually released to the live network. This pipeline automates our release process, making it much easier to quickly and reliably ship code. It's also simple to reason about.

Branches and Trains

The branches and their corresponding trains that comprise the stages of the release pipeline are:

Branch	Train	Target audience
`develop`	`edge`	Runtime developers
`release`	`soon`	Early adopters
`master`	`live`	Everyone else

develop is the default branch in the repo, which means that all new pull requests target it by default. The general flow of a new feature or bug fix through the pipeline is:

feature branch ----> develop ----> release ----> master
                        |             |             |
                    deployed to    deployed to   deployed to
                    edge train     soon train    live train

If an issue arises in the course of testing the release branch (because more people are using soon than edge), a PR can be opened to target release. If that's the case, the master needs to be merged back into develop after release merges into master to ensure that develop gets the fix.

Version Numbers

Each time a commit is pushed to develop, release, or master--say, when a PR merges--we build and deploy a new version of the binary available for consumption by anyone subscribed to that train (via <pier>/.bin/pace).

For edge and soon, each binary is given a version of the form {version number}-{shortened commit SHA}, where {version number} is the version number listed in the version file in the root of this repo and {shortened commit SHA} is the shortened commit SHA of the commit the binary was built from. This allows subscribers to edge and soon to continually pull down new binaries via the next subcommand even when the version number in the version file remains the same.

For master, each binary is given a version of the form {version number}, where {version number} is simply the version number listed in the version file in the root of this repo.

Each time a release is cut (i.e. develop is merged into release to kick off a release), the version number should be bumped on develop in anticipation of the next release.

Deploy Endpoints

Binaries are deployed to the following endpoints, where {VN} is the version number in VERSION, {CS} is the shortened commit SHA of the commit the binary is built from, and {P} is one of linux-aarch64, linux-x86_64, macos-aarch64, and macos-x86_64:

The most recently deployed version of a given train (pace) is uploaded to https://bootstrap.urbit.org/vere/{T}/last, where {T} is one of edge, soon, and live:

Releases

In anticipation of a new release to live, create a new pull request targeting master from release.

When you're ready to release to live, tag the tip of release with a tag of the form vere-v{version}, where {version} is the contents of VERSION:

$ cd path/to/vere/repo
$ git checkout release
$ git fetch origin && git merge origin/release
$ git tag vere-v$(cat VERSION)
$ git push origin vere-v$(cat VERSION)

Then merge the pull request, which triggers the deployment of the live binaries. Once the binaries have been deployed, which usually takes about thirty minutes, create a GitHub release using the following checklist:

Select the just-created tag as the tag for the release.
Select master as the target for the release.
Use the tag name (i.e. vere-v1.17) as the title of the release.
Select the prevoius release's tag (i.e. vere-v1.16) as the previous tag.
Click "Generate release notes".
Add the following information above the autogenerated ## What's Changed section:

Arvo {Kelvin version}K
Vere {Vere version}

## Description
{Notes describing the release}

Upload a tarball of the binary to the release for each platform we support. Generate a platform's tarball using the following commands, where {platform} is one of linux-aarch64, linux-x86_64, macos-aarch64, and macos-x86_64:

$ wget https://bootstrap.urbit.org/vere/live/v{version}/vere-v{version}-{platform}
$ chmod +x vere-v{version}-{platform}
$ tar zcf {platform}.tgz vere-v{version}-{platform}

Check the box marked "Set as the latest release".
Click "Publish release".
Create a placeholder pill for the new binary exists by running gsutil cp gs://bootstrap.urbit.org/urbit-vOLD.pill gs://bootstrap.urbit.org/urbit-vNEW.pill
Ensure that a new urbit can be booted by using the Getting Started guide
Post the contents of the GH Release notes to the urbit-dev mailing list

Post an announcement to the urbit-dev mailing list containing a copy of the release notes. When in doubt, follow the format of the previous release's announcement. Also post an announcement to the "General" channel of the Urbit Community group.

Updating Infrastructure Ships

~zod and other live galaxies (TODO which?) should all be updated to the new binary, to make sure they will be ready to install and deploy Arvo releases on the latest Kelvin.
~marzod and other live stars (TODO which?) should also be updated to the new binary.
Ships that host official UF groups should be updated: ~bitdeg, ~halbex-palheb, TODO: more.

Preparing for the Next Release

This instructions are performed on release day to prepare the next release candidate.

Merge master into develop (to ensure any changes made to master are reflected back into develop)
- git fetch --all
- git checkout master
- git reset --hard origin/master
- git checkout -b merge-master-v{version}-into-develop
- git push origin merge-master-v{version}-into-develop
- Create, approve, and merge a pull request from merge-master-v{version}-into-develop into master
Merge develop into release (to ensure any changes made to develop are reflected back into release)
- git fetch --all
- git checkout develop
- git reset --hard origin/develop
- git checkout -b merge-develop-v{version}-into-release
- git push origin merge-develop-v{version}-into-release
- Create, approve, and merge a pull request from merge-develop-v{version}-into-release into release
Bump the version number on develop
- git fetch --all
- git checkout develop
- git reset --hard origin/develop
- git checkout -b bump-version-v{version}-to-v{next-version}
- echo {next-version} > VERSION
- git add VERSION
- git commit -m "Bump version to v{next-version}"
- git push origin bump-version-v{version}-to-v{next-version}
- Create, approve, and merge a pull request from bump-version-v{version}-to-v{next-version} into develop

7.7 KiB Raw Blame History