meta: add a basic maintainers' guide [ci skip]

MAINTAINERS.md

@@ -0,0 +1,178 @@
+# 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.
+