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.
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.
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.
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
:
- https://bootstrap.urbit.org/vere/edge/v{VN}-{CS}/vere-v{VN}-{CS}-{P}
- https://bootstrap.urbit.org/vere/soon/v{VN}-{CS}/vere-v{VN}-{CS}-{P}
- https://bootstrap.urbit.org/vere/live/v{VN}/vere-v{VN}-{P}
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
.
We also upload binaries for next/kelvin/*
branches, where {K}
is the Kelvin
version of the branch:
Last deployed version strings for the next/kelvin/*
branches are uploaded to:
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 oflinux-aarch64
,linux-x86_64
,macos-aarch64
, andmacos-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.
-
~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.
This instructions are performed on release day to prepare the next release candidate.
- Merge
master
intodevelop
(to ensure any changes made tomaster
are reflected back intodevelop
)-
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
intomaster
-
- Merge
develop
intorelease
(to ensure any changes made todevelop
are reflected back intorelease
)-
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
intorelease
-
- 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}
intodevelop
-