urbit/shrub
1
1
Fork 0
mirror of https://github.com/urbit/shrub.git synced 2024-12-19 00:13:12 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #5382 from urbit/philip/branches

Browse Source 
meta: update branch conventions
This commit is contained in:
Philip Monk 2022-01-04 19:52:51 -07:00 committed by GitHub
commit 04246b9c38
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 58 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

120
MAINTAINERS.md
View File

@ -29,7 +29,7 @@ released.
### Release branches ### Release branches
Release branches are code that is ready to release. All release branch names Release branches are code that is ready to release. All release branch names
should start with `release/`. should start with `next/`.
All code must be reviewed before being pushed to a release branch. Thus, All code must be reviewed before being pushed to a release branch. Thus,
feature branches should be PR'd against a release branch, not master. feature branches should be PR'd against a release branch, not master.
@ -41,57 +41,55 @@ be released together -- unless one of the underlying commits is separately put
on a release branch. on a release branch.
Here's a worked example. The rule is to make however many branches are useful, Here's a worked example. The rule is to make however many branches are useful,
and no more. This example is not prescriptive, the developers making the and no more. This example is not prescriptive; the developers making the
changes may add, remove, or rename branches in this flow at will. changes may add, remove, or rename branches in this flow at will.
Suppose you (plural, the dev community at large) complete some work in a Suppose you (plural, the dev community at large) complete some work in a
userspace app, and you put it in `release/next-userspace`. Separately, you make userspace app, and you put it in `next/landscape`. Separately, you make a small
a small JS change. If you PR it to `release/next-userspace`, then it will only JS change. If you PR it to `next/landscape`, then it will only be released at
be released at the same time as the app changes. Maybe this is fine, or maybe the same time as the app changes. Maybe this is fine, or maybe you want this
you want this change to go out quickly, and the change in change to go out quickly, and the change in `next/landscape` is relatively
`release/next-userspace` is relatively risky, so you don't want to push it out risky, so you don't want to push it out on Friday afternoon. In this case, put
on Friday afternoon. In this case, put the change in another release branch, the change in another release branch, say `next/js`. Now either can be released
say `release/next-js`. Now either can be released independently. independently.
Suppose you do further work that you want to PR to `release/next-userspace`, but Suppose you do further work that you want to PR to `next/landscape`, but it
it depends on your fixes in `release/next-js`. Simply merge `release/next-js` depends on your fixes in `next/js`. Simply merge `next/js` into either your
into either your feature branch or `release/next-userspace` and PR your finished feature branch or `next/landscape` and PR your finished work to
work to `release/next-userspace`. Now there is a one-way coupling: `next/landscape`. Now there is a one-way coupling: `next/landscape` contains
`release/next-userspace` contains `release/next-js`, so releasing it will `next/js`, so releasing it will implicitly release `next/js`. However, you can
implicitly release `release/next-js`. However, you can still release still release `next/js` independently.
`release/next-js` independently.
This scheme extends to other branches, like `release/next-kernel` or This scheme extends to other branches, like `next/base` or `next/os1.1` or
`release/os1.1` or `release/ford-fusion`. Some branches may be long-lived and `next/ford-fusion`. Some branches may be long-lived and represent simply the
represent simply the "next" release of something, while others will have a "next" release of something, while others will have a definite lifetime that
definite lifetime that corresponds to development of a particular feature or corresponds to development of a particular feature or numbered release.
numbered release.
Since they are "done", release branches should be considered "public", in the Since they are "done", release branches should be considered "public", in the
sense that others may depend on them at will. Thus, never rebase a release sense that others may depend on them at will. Thus, never rebase a release
branch. branch.
When cutting a new release, you can filter branches with `git branch --list When cutting a new release, you can filter branches with `git branch --list
'release/*'` or by typing "release/" in the branch filter on Github. This will 'next/*'` or by typing "next/" in the branch filter on Github. This will give
give you the list of branches which have passed review and may be merged to you the list of branches which have passed review and may be merged to master
master and released. When choosing which branches to release, make sure you and released. When choosing which branches to release, make sure you understand
understand the risks of releasing them immediately. If merging these produces the risks of releasing them immediately. If merging these produces nontrivial
nontrivial conflicts, consider asking the developers on those branches to merge conflicts, consider asking the developers on those branches to merge between
between themselves. In many cases a developer can do this directly, but if it's themselves. In many cases a developer can do this directly, but if it's
sufficiently nontrivial, this may be a reviewed PR of one release branch into sufficiently nontrivial, this may be a reviewed PR of one release branch into
another. another.
### Non-OTAable release branches #### Standard release branches
In some cases, work is completed which cannot be OTA'd as written. For example, While you can always create non-standard release branches to stage for a
the code may lack state adapters, or it may not properly handle outstanding particular release, most changes should go through the following:
subscriptions. It could also be code which is planned to be released only upon
a breach (network-wide or rolling).
In this case, the code may be PR'd to a `na-release/` branch. All rules are the - next/base -- changes to the %base desk in pkg/arvo
same as for release branches, except that the code does not need to apply - next/garden -- changes to the %garden desk
cleanly to an existing ship. If you later write state adapter or otherwise make - next/landscape -- changes to the %landscape desk
it OTAable, then you may PR it to a release branch. - next/bitcoin -- changes to the %bitcoin desk
- next/webterm -- changes to the %webterm desk
- next/vere -- changes to the runtime
### Other cases ### Other cases
@ -163,9 +161,10 @@ If you're making a Vere release, just play it safe and update all the pills.
For an Urbit OS release, after all the merge commits, make a release with the For an Urbit OS release, after all the merge commits, make a release with the
commit message "release: urbit-os-v1.0.xx". This commit should have up-to-date commit message "release: urbit-os-v1.0.xx". This commit should have up-to-date
artifacts from pkg/interface and a new solid pill. If neither the pill nor the artifacts from pkg/interface and a new version number in the desk.docket-0 of
JS need to be updated (e.g if the pill was already updated in the previous merge any desk which changed. If neither the pill nor the JS need to be updated (e.g
commit), consider making the release commit with --allow-empty. if the pill was already updated in the previous merge commit), consider making
the release commit with --allow-empty.
If anything in `pkg/interface` has changed, ensure it has been built and If anything in `pkg/interface` has changed, ensure it has been built and
deployed properly. You'll want to do this before making a pill, since you want deployed properly. You'll want to do this before making a pill, since you want
@ -191,21 +190,23 @@ What you should do here depends on the type of release being made.
First, for Urbit OS releases: First, for Urbit OS releases:
If it's a very trivial hotfix that you know isn't going to break If it's a very trivial hotfix that you know isn't going to break anything, tag
anything, tag it as `urbit-os-vx.y.z`. Here 'x' refers to the product version it as `urbit-os-vx.y`. Here 'x' is the major version and 'y' is an OTA patch
(e.g. OS1, OS2..), 'y' to the continuity era in that version, and 'z' to an counter. Change `urbit-os` to e.g. `landscape` or another desk if that's what you're
OTA patch counter. So for a hotfix version, you'll just want to increment 'z'. releasing. If you're releasing changes to more than one desk, add a separate
tag for each desk (but only make one announcment email/post, with all of the
desks listed).
Use an annotated tag, i.e. Use an annotated tag, i.e.
``` ```
git tag -a urbit-os-vx.y.z git tag -a urbit-os-vx.y
``` ```
The tag format should look something like this: The tag format should look something like this:
``` ```
urbit-os-vx.y.z urbit-os-vx.y
This release will be pushed to the network as an over-the-air update. This release will be pushed to the network as an over-the-air update.
@ -236,17 +237,17 @@ 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. 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 If it's *not* a trivial hotfix, you should probably make any number of release
candidate tags (e.g. `urbit-os-vx.y.z.rc1`, `urbit-os-vx.y.z.rc2`, ..), test candidate tags (e.g. `urbit-os-vx.y.rc1`, `urbit-os-vx.y.rc2`, ..), test
them, and after you confirm one of them is good, tag the release as them, and after you confirm one of them is good, tag the release as
`urbit-os-vx.y.z`. `urbit-os-vx.y`.
For Vere releases: For Vere releases:
Tag the release as `urbit-vx.y.z`. The tag format should look something like Tag the release as `urbit-vx.y`. The tag format should look something like
this: this:
``` ```
urbit-vx.y.z urbit-vx.y
Note that this Vere release will by default boot fresh ships using an Urbit OS Note that this Vere release will by default boot fresh ships using an Urbit OS
va.b.c pill. va.b.c pill.
@ -254,10 +255,10 @@ va.b.c pill.
Release binaries: Release binaries:
(linux64) (linux64)
https://bootstrap.urbit.org/urbit-vx.y.z-linux64.tgz https://bootstrap.urbit.org/urbit-vx.y-linux64.tgz
(macOS) (macOS)
https://bootstrap.urbit.org/urbit-vx.y.z-darwin.tgz https://bootstrap.urbit.org/urbit-vx.y-darwin.tgz
Release notes: Release notes:
@ -295,10 +296,10 @@ and stars to the rest of the network.
For consistency, I create a 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/urbit-os-vx.y.z.tar.gz $ wget https://github.com/urbit/urbit/archive/urbit-os-vx.y.tar.gz
$ tar xzf urbit-os-vx.y.z.tar.gz $ tar xzf urbit-os-vx.y.tar.gz
$ herb zod -p hood -d "+hood/mount /=home=" $ herb zod -p hood -d "+hood/mount /=home="
$ rsync -zr --delete urbit-urbit-os-vx.y.z/pkg/arvo/ zod/home $ rsync -zr --delete urbit-urbit-os-vx.y/pkg/arvo/ zod/home
$ herb zod -p hood -d "+hood/commit %home" $ herb zod -p hood -d "+hood/commit %home"
$ herb zod -p hood -d "+hood/merge %kids our %home" $ herb zod -p hood -d "+hood/merge %kids our %home"
``` ```
@ -306,16 +307,11 @@ $ herb zod -p hood -d "+hood/merge %kids our %home"
For Vere updates, this means simply shutting down each desired ship, installing For Vere updates, this means simply shutting down each desired ship, installing
the new binary, and restarting the pier with it. the new binary, and restarting the pier with it.
#### Continuous deployment
A subset of release branches are deployed continuously to the network. Thus far
this only includes `release/next-userspace`, which deploys livenet-compatible
changes to select QA ships. Any push to master will automatically
merge master into `release/next-userspace` to keep the streams at parity.
### Announce the update ### Announce the update
Post an announcement to urbit-dev. The tag annotation, basically, is fine here Post an announcement to urbit-dev. The tag annotation, basically, is fine here
-- I usually add the %base hash (for Urbit OS releases) and the release binary -- I usually add the %cz hash (for Urbit OS releases) and the release binary
URLs (for Vere releases). Check the urbit-dev archives for examples of these URLs (for Vere releases). Check the urbit-dev archives for examples of these
announcements. announcements.
Post the same announcement to the group feed of Urbit Community.