1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
|
# 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`.
### `next/kelvin/*` Endpoints
We also upload binaries for `next/kelvin/*` branches, where `{K}` is the Kelvin
version of the branch:
- https://bootstrap.urbit.org/vere/next/kelvin/{K}/v{VN}-{CS}/vere-v{VN}-{CS}-{P}
Last deployed version strings for the `next/kelvin/*` branches are uploaded to:
- https://bootstrap.urbit.org/vere/next/kelvin/{K}/last
## 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`
|
