vere/MAINTAINERS.md

# 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`