mirror of
https://github.com/urbit/shrub.git
synced 2024-12-20 01:01:37 +03:00
179 lines
4.8 KiB
Markdown
179 lines
4.8 KiB
Markdown
|
# Maintainers' Guide
|
||
|
|
||
|
## Hotfixes
|
||
|
|
||
|
Here lies an informal guide for making hotfix releases and deploying them to
|
||
|
the network.
|
||
|
|
||
|
Take [this recent PR][1], as an example. This constituted a great hotfix.
|
||
|
It's a single commit, targeting a problem that existed on the network at the
|
||
|
time. Here's it should be released and deployed OTA.
|
||
|
|
||
|
[1]: https://github.com/urbit/urbit/pull/2025
|
||
|
|
||
|
### If the thing is acceptable to merge, merge it to master
|
||
|
|
||
|
Unless it's very trivial, it should probably have a single "credible looking"
|
||
|
review from somebody else on it.
|
||
|
|
||
|
You can just merge the PR in GitHub. As I, `~nidsut-tomdun`, am a l33t
|
||
|
h4x0r, I use a custom merge commit format, gotten by:
|
||
|
|
||
|
```
|
||
|
git merge --no-ff --signoff --log BRANCH
|
||
|
```
|
||
|
|
||
|
with the commit message:
|
||
|
|
||
|
```
|
||
|
Merge branch FOO (#PR_NUM)
|
||
|
|
||
|
* FOO:
|
||
|
bar: ...
|
||
|
baz: ...
|
||
|
|
||
|
Signed-off-by: Jared Tobin <jared@tlon.io>
|
||
|
```
|
||
|
|
||
|
All this extra wankery is hardly required, but IMO it's nice to have the
|
||
|
commit log information in the merge commit, which GitHub's "Merge PR" button
|
||
|
doesn't do (at least by default).
|
||
|
|
||
|
The script at `sh/merge-with-custom-message` can be used to make this simple(r)
|
||
|
to do. I use `git mu` as an alias for it, locally.
|
||
|
|
||
|
### Apply the changes to this era's release branch
|
||
|
|
||
|
This corresponds to the 'vx.y' part of the most recent 'urbit vx.y.z' release.
|
||
|
At the time of writing, we're on v0.10 (and I'll use this branch as a running
|
||
|
example):
|
||
|
|
||
|
If the branch doesn't yet exist, just create it via:
|
||
|
|
||
|
```
|
||
|
git checkout -b v0.10 master
|
||
|
```
|
||
|
|
||
|
If you can get away with merging master to v0.10 without pulling in any
|
||
|
superfluous commits, feel free to do that. Otherwise, you'll want to cherry
|
||
|
pick the commits like so:
|
||
|
|
||
|
```
|
||
|
git cherry-pick -x TARGET_COMMITS
|
||
|
```
|
||
|
|
||
|
Use the `-x` flag to `git-cherry-pick`, because this will indicate in the
|
||
|
commit message where the things originally came from.
|
||
|
|
||
|
Create Landscape or alternative pill builds, if or as appropriate (i.e., if
|
||
|
anything in Landscape changed -- don't trust the compiled JS/CSS that's
|
||
|
included in the commit).
|
||
|
|
||
|
You may also want to create a brass pill, in particular, as it's convenient for
|
||
|
tooling to be able to boot directly from a given release.
|
||
|
|
||
|
### Tag the resulting commit
|
||
|
|
||
|
What you should do here depends on the type of release being made.
|
||
|
|
||
|
First, for Arvo releases:
|
||
|
|
||
|
If it's a very trivial hotfix that you know isn't going to break
|
||
|
anything, tag it as `arvo.yyyy.mm.dd`. Use an annotated tag, i.e.
|
||
|
|
||
|
```
|
||
|
git tag -a arvo.yyyy.mm.dd
|
||
|
```
|
||
|
|
||
|
The tag format should look something like this:
|
||
|
|
||
|
```
|
||
|
arvo.yyyy.mm.dd
|
||
|
|
||
|
This release contains Arvo changes that will be pushed to the live
|
||
|
network as an over-the-air update.
|
||
|
|
||
|
Release notes:
|
||
|
|
||
|
[..]
|
||
|
|
||
|
Contributions:
|
||
|
|
||
|
[..]
|
||
|
```
|
||
|
|
||
|
You can get the "contributions" section by the shortlog between the
|
||
|
last release and this release:
|
||
|
|
||
|
```
|
||
|
git log --pretty=short --no-merges \
|
||
|
LAST_RELEASE..v0.10 | git shortlog
|
||
|
```
|
||
|
|
||
|
I originally tried to curate this list somewhat, but now just paste it
|
||
|
verbatim. If it's too noisy, yell at your colleagues to improve their commit
|
||
|
messages.
|
||
|
|
||
|
Try to include a high-level summary of the changes in the "release notes"
|
||
|
section. You should be able to do this by simply looking at the git log and
|
||
|
skimming the commit descriptions (or perhaps copying some of them in verbatim).
|
||
|
If the commit descriptions are too poor to easily do this, then again, yell at
|
||
|
your fellow contributors to make them better in the future.
|
||
|
|
||
|
If it's *not* a trivial hotfix, you should probably make any number of release
|
||
|
candidate tags (e.g. `arvo.yyyy.mm.dd.rc-1`, `arvo.yyyy.mm.dd.rc-2`, ..), test
|
||
|
them, and after you confirm one of them is good, tag the release as
|
||
|
`arvo.yyyy.mm.dd`.
|
||
|
|
||
|
For Vere releases:
|
||
|
|
||
|
Tag the release as `vx.y.z`. The tag format should look something
|
||
|
like this:
|
||
|
|
||
|
```
|
||
|
urbit vx.y.z
|
||
|
|
||
|
This release contains Vere changes, so users should update their
|
||
|
binaries.
|
||
|
|
||
|
This is not a breaching release, so users should not create new
|
||
|
piers.
|
||
|
|
||
|
Release notes:
|
||
|
|
||
|
[..]
|
||
|
|
||
|
Contributions:
|
||
|
|
||
|
[..]
|
||
|
```
|
||
|
|
||
|
The same schpeel re: release candidates applies here.
|
||
|
|
||
|
You should probably avoid putting both Arvo and Vere changes into Vere
|
||
|
releases.
|
||
|
|
||
|
### Deploy the update
|
||
|
|
||
|
For Arvo updates, this means copying the files into ~zod's %base desk. For
|
||
|
consistency, I download the release tarball and then rsync the files in:
|
||
|
|
||
|
```
|
||
|
$ wget https://github.com/urbit/urbit/archive/arvo.yyyy.mm.dd.tar.gz
|
||
|
$ tar xzf arvo.yyyy.mm.dd.tar.gz
|
||
|
$ herb zod -p hood -d "+hood/mount /=base="
|
||
|
$ rsync -zr --delete urbit-arvo.yyyy.mm.dd/pkg/arvo/ zod/base
|
||
|
$ herb zod -p hood -d "+hood/commit %base"
|
||
|
```
|
||
|
|
||
|
For Vere updates, this means shutting down each desired ship, installing the
|
||
|
new binary, and restarting the pier with it.
|
||
|
|
||
|
### Announce the update
|
||
|
|
||
|
Post an announcement to urbit-dev. The tag annotation, basically, is fine here
|
||
|
-- I usually add the %base hash (for Arvo releases) and the release binary URLs
|
||
|
(for Vere releaes). Check the urbit-dev archives for examples of these
|
||
|
announcements.
|
||
|
|