mirror of
https://github.com/urbit/vere.git
synced 2024-09-11 11:55:31 +03:00
168 lines
7.7 KiB
Markdown
168 lines
7.7 KiB
Markdown
# 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:
|
|
|
|
```console
|
|
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][version]
|
|
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][version] 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][version].
|
|
|
|
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`:
|
|
|
|
- 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`:
|
|
|
|
## 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][version]:
|
|
```console
|
|
$ 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:
|
|
```text
|
|
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`:
|
|
```console
|
|
$ 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](https://urbit.org/getting-started/cli)
|
|
- [ ] Post the contents of the GH Release notes to the [urbit-dev mailing list](https://groups.google.com/a/urbit.org/g/dev)
|
|
|
|
Post an announcement to the [urbit-dev mailing
|
|
list][urbit-dev] 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][urbit-community].
|
|
|
|
[urbit-community]: https://urbit.org/groups/~bitbet-bolbel/urbit-community
|
|
[urbit-dev]: https://groups.google.com/a/urbit.org/g/dev
|
|
[version]: https://github.com/urbit/vere/tree/develop/VERSION
|
|
|
|
## 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`
|