diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index be393a610..1a1b08a2d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -158,9 +158,8 @@ commit that updates the source. ## Releases -We typically create releases by cherry picking appropriate commits from -`master` and tagging the result, so any given commit in `master` may not -actually be present in the latest release. +We typically create releases by tagging appropriate commits on `master`, so any +given commit in `master` may not actually be present in the latest release. We perform updates by pushing releases over-the-air to `~zod` approximately once per week, so any contribution that can be deployed OTA will usually find diff --git a/MAINTAINERS.md b/MAINTAINERS.md index 20624c52c..ee57f8dab 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -45,87 +45,40 @@ to use. My .git/config contains the following, for example: so that I can type e.g. `git mu origin/foo 1337`. -### Apply the changes to this era's release branch +### Prepare a release commit -For now, the release branch corresponds to the `vx.y` part of the most recent -Vere release (i.e., `urbit vx.y.z`). 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 or non-OTA-able 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. - -A useful technique is to cherry-pick merge commits on master directly. Take -following commit, for example: - -``` -commit 769996d09 -Merge: 171fcbd26 8428f0ab1 -Author: Jared Tobin -Date: Sun Feb 2 19:11:04 2020 +0400 - - Merge branch 'liam-fitzgerald/langserver-doc-autocomplete' (#2204) - - * liam-fitzgerald/langserver-doc-autocomplete: - language-server: magic-spoon hover, autocomplete - language-server: build ford prelude - language-server: dynamically compute subject - language-server: revive rune/symbol completion - language-server: add completion JSON parsers - - Signed-off-by: Jared Tobin -``` - -rather than cherry-picking the individual commits, one could just use the -following while on the release branch: - -``` -git cherry-pick -x -m 1 769996d09 -``` - -you can check the man page for `git-cherry-pick(1)` for details here. - -Create Landscape or alternative pill builds, if or as appropriate (i.e., if -anything in Landscape changed -- don't trust any compiled JS/CSS that's -included in the commit). +You should create Landscape or alternative pill builds, if or as appropriate +(i.e., if anything in Landscape changed -- don't trust any compiled JS/CSS +that's included in the commit), and commit these in a release commit. You should always create a solid pill, in particular, as it's convenient for -tooling to be able to boot directly from a given release. If you're making a -Vere release, just play it safe and update all the pills. +tooling to be able to boot directly from a given release. + +If you're making a Vere release, just play it safe and update all the pills. ### Tag the resulting commit What you should do here depends on the type of release being made. -First, for Arvo releases: +First, for Urbit OS 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. +anything, tag it as `urbit-os-vx.y.z`. Here 'x' refers to the product version +(e.g. OS1, OS2..), 'y' to the continuity era in that version, and 'z' to an +OTA patch counter. So for a hotfix version, you'll just want to increment 'z'. + +Use an annotated tag, i.e. ``` -git tag -a arvo.yyyy.mm.dd +git tag -a urbit-os-vx.y.z ``` The tag format should look something like this: ``` -arvo.yyyy.mm.dd +urbit-os-vx.y.z -This release contains Arvo changes that will be pushed to the live -network as an over-the-air update. +This release will be pushed to the network as an over-the-air update. Release notes: @@ -154,23 +107,25 @@ 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.rc1`, `arvo.yyyy.mm.dd.rc2`, ..), test +candidate tags (e.g. `urbit-os-vx.y.z.rc1`, `urbit-os-vx.y.z.rc2`, ..), test them, and after you confirm one of them is good, tag the release as -`arvo.yyyy.mm.dd`. +`urbit-os-vx.y.z`. For Vere releases: -Tag the release as `vx.y.z`. The tag format should look something -like this: +Tag the release as `urbit-vx.y.z`. The tag format should look something like +this: ``` -urbit vx.y.z +urbit-vx.y.z -This release contains Vere changes, so users should update their -binaries. +Release binaries: -This is not a breaching release, so users should not create new -piers. +(linux64) +https://bootstrap.urbit.org/urbit-vx.y.z-linux64.tgz + +(macOS) +https://bootstrap.urbit.org/urbit-vx.y.z-darwin.tgz Release notes: @@ -183,23 +138,26 @@ Contributions: The same schpeel re: release candidates applies here. -Do not include implicit Arvo changes in Vere releases. This used to be done, -historically, but shouldn't be any longer. If there are Arvo and Vere changes -to be released, make two releases. +Do not include implicit Urbit OS changes in Vere releases. This used to be +done, historically, but shouldn't be any longer. If there are Urbit OS and +Vere changes to be released, make two releases. ### Deploy the update -For Arvo updates, this means copying the files into ~zod's %base desk. The +(**Note**: the following steps are automated by some other Tlon-internal +tooling. Just ask `~nidsut-tomdun` for details.) + +For Urbit OS updates, this means copying the files into ~zod's %base desk. The changes will be synced to /~zod/kids and then propagated through other galaxies and stars to the rest of the network. -For consistency, I download the release tarball and then rsync the files in: +For consistency, I create a 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 +$ wget https://github.com/urbit/urbit/archive/urbit-os-vx.y.z.tar.gz +$ tar xzf urbit-os-vx.y.z.tar.gz $ herb zod -p hood -d "+hood/mount /=base=" -$ rsync -zr --delete urbit-arvo.yyyy.mm.dd/pkg/arvo/ zod/base +$ rsync -zr --delete urbit-urbit-os-vx.y.z/pkg/arvo/ zod/base $ herb zod -p hood -d "+hood/commit %base" ``` @@ -209,7 +167,7 @@ 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 releases). Check the urbit-dev archives for examples of these +-- I usually add the %base hash (for Urbit OS releases) and the release binary +URLs (for Vere releases). Check the urbit-dev archives for examples of these announcements.