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

Merge pull request #6203 from urbit/i/6198/repo-docs

Browse Source 
docs: update current release processes
This commit is contained in:
Zach Alberico 2023-01-19 15:10:37 -07:00 committed by GitHub
commit 23a5839e5c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 238 additions and 604 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

376
CONTRIBUTING.md
View File

@ -1,141 +1,101 @@
# Contributing to Urbit
## Workflow
Thank you for your interest in contributing to Urbit.
Before beginning any unit of work, you should have a GitHub issue detailing the
scope of the work. This could be an issue someone else filed and has been
assigned to you (or you've assigned to yourself) or a new issue you filed
specifically for this unit of work. As much as possible, discussion of the work
should take place in the issue. When this is not possible, please update the
issue with relevant details from any offline conversations. Each issue should
provide a clear and thorough history of the work from inception to completion.
See [urbit.org/using/install][start] for basic orientation and usage
instructions. You may also want to subscribe to [urbit-dev][list], the Urbit
development mailing list. For specific information on contributing to the Urbit
interface, see its [contribution guidelines][interface].
## Issues
For information on Arvo's maintainers, see [pkg/arvo][main].
The [GitHub tracker][issu] is our canonical source of truth around issues, bugs,
performance problems and feature requests. If you encounter any issues when
developing on Urbit, feel free to submit a report about it here.
For more extensive information on Urbit development, such as how to set up an
environment and how to submit a grant, see the [developer documentation][dev].
A good bug report, description of a crash, etc., should ideally be
*reproducible*, with clear steps as to how another developer can replicate and
examine your problem. That said, this isn't always possible -- some bugs depend
on having created a complicated or unusual state, or can otherwise simply be
difficult to trigger again.
[start]: https://urbit.org/using/install
[interface]: /pkg/interface/CONTRIBUTING.md
[dev]: https://urbit.org/docs/development
Your issue should thus at a minimum be *informative*. The best advice here is
probably "don't write bad issues," where "bad" is a matter of judgment and
taste. Issues that the maintainers don't judge to be sufficiently useful or
informative may be closed.
## Fake ships
Feature requests are welcome, but they should include sufficient detail and
explanation, as well as a discussion of perceived benefits one could expect from
them. "It would be cool if.." probably does not, in itself, constitute a good
feature request; instead, try to be specific about what you're requesting, and
what your desired feature would accomplish.
You may have an identity on the live network, but doing all your development on
the live network would be cumbersome and unnecessary. Standard practice in
Urbit development is to work on a fake `~zod`. Fake ships use deterministic
keys (derived from the ship address) and don't talk to the live network. They
can talk to each other over the local loopback.
### Feature Branch Names
To start a fake ship, simply specify the name with `-F`:
Every branch that you intend to put up for review must adhere to the form
`i/<N>/<...>`, where `<N>` is the number of the issue that the branch
corresponds to and `<...>` is an optional short description of the branch to aid
in readability. If `<...>` is omitted, the `/` should be omitted as well, which
makes `i/<N>` a well-formed branch name. These feature branches should be based
off of `develop`.
```
$ urbit -F zod
```
### Commits
You can also pass a name for the *pier* (or ship directory):
```
$ urbit -F zod -c my-fake-zod
```
To resume a fake ship, just pass the name of the pier:
```
$ urbit my-fake-zod
```
Fake ships by default use the same pre-compiled kernelspace ('pills') as livenet
ships do: boot pills, which are not always current with `master`. If you wish to
develop using code off the master branch, run the following from the repo
directory:
```
git lfs install
git lfs pull
urbit -F zod -B "bin/solid.pill" -A "pkg/arvo"
```
## Git practice
### Contributing
The canonical source tree is the `master` branch of
[https://github.com/urbit/urbit][repo]. You should typically branch off of
`master` when commencing new work. Most pull requests should be merging into
one of the `next/*` branches, depending on what part of the system the pull
request is targeting.
Since we use GitHub, we request you contribute via a GitHub pull request. Tag
the [maintainer][main] for the component. If you have a question for the
maintainer, you can direct message them from your Urbit ship using that
information.
When contributing changes, via whatever means, make sure you describe them
appropriately. You should attach a reasonably high-level summary of what the
changes are and what they do; reference any useful background material that may
exist, e.g. a GitHub issue, a mailing list discussion, a UP, etc. [Here][jbpr]
is a good example of a pull request with a useful, concise description.
If your changes replace significant extant functionality, be sure to compare
them with the thing you're replacing. You may also want to cc reviewers,
or other parties who might have a particular interest in what you're
contributing.
[jbpr]: https://github.com/urbit/urbit/pull/1782
### Hygiene
Commits should generally be relevant, atomic, and have descriptions formatted
in the following manner:
Commits should generally be relevant, atomic, and have descriptions formatted in
the following manner:
> component: short description
>
> long description
The 'component' is a short prefix of what area of the codebase the commit
applies to. If a commit patches `%gall`, for example, the description should
be prefixed by 'gall'. If it touches `:aqua`, it should be prefixed by 'aqua'.
If it touches multiple components, then separate these by commas, e.g. "gall,
aqua, ph" -- but note that this may be a warning that too many changes are
being packed into a single commit. The 'component' and 'short description'
combined should be no more than 50 characters.
applies to. If a commit patches `%gall`, for example, the description should be
prefixed by 'gall'. If it touches `:aqua`, it should be prefixed by 'aqua'. If
it touches multiple components, then separate these by commas, e.g. "gall, aqua,
ph" -- but note that this may be a warning that too many changes are being
packed into a single commit. The 'component' and 'short description' combined
should be no more than 50 characters.
A lengthier description is encouraged, where useful, but is not always strictly
required. You should use the longer description to give any useful background
on or motivation for the commit, provide a summary of what it does, link to
relevant issues, proposals, or other commits, and so on.
Every individual commit should at a minimum be in a compiling and runnable state.
Broken commits or commits simply marked "wip" are not allowed. If you need to
clean up the commits in your branch, you can soft reset to an earlier state and
recommit with better metadata (or if the change is small enough, squash to one
good commit at the end).
A lengthier description is encouraged, but is not always strictly required. You
should use the longer description to give any useful background on or motivation
for the commit, provide a summary of what it does, link to relevant issues,
proposals, or other commits, and so on.
Here is an example of our commit format, taken from a commit in the history:
> zuse: remove superfluous 'scup' and 'culm' types.
>
> %zuse includes definitions for 'scup' and 'culm', both of which are
> superfluous. 'scup' is simply (pair ship desk) and is used only in
> the definition of 'culm', a tagged union in which three of the four
> branches are commented out (i.e. are unused).
> superfluous. 'scup' is simply (pair ship desk) and is used only in the
> definition of 'culm', a tagged union in which three of the four branches are
> commented out (i.e. are unused).
>
> This commit deletes 'scup' and 'culm' and refactors what little code
> made use of them.
> This commit deletes 'scup' and 'culm' and refactors what little code made use
> of them.
Note that the short description is prefixed by `zuse:`, which is what the
commit touches. Otherwise it just includes a summary of the change.
Note that the short description is prefixed by `zuse:`, which is what the commit
touches. Otherwise it just includes a summary of the change.
Here's another example:
> build: give arvo a high priority
>
> 0bdced981e4 introduced the 'arvo-ropsten' derivation. Attempting to
> install both 'arvo' and 'arvo-ropsten' via nix-env will result in a
> priority error; this assigns a higher priority to 'arvo' to resolve the
> conflict.
> 0bdced981e4 introduced the 'arvo-ropsten' derivation. Attempting to install
> both 'arvo' and 'arvo-ropsten' via nix-env will result in a priority error;
> this assigns a higher priority to 'arvo' to resolve the conflict.
>
> Fixes #1912.
Note that it cites a previous relevant commit, `0bdced981e4`, in its summary,
and also points at the issue that it resolves.
If you're in doubt about how to format your commit descriptions, take a look at
the recent history and try to mimic the style that you can see others broadly
follow there.
When we say commits should be "atomic", we mean with respect to some distinct
logical unit, e.g. a type definition used across many files, or a single file,
or just a single function in a single file. Commits should be atomic at the
@ -144,104 +104,83 @@ into a single one that captures everything you're trying to do -- the history
will never make for pleasant bedtime reading, so focus instead on making your
commits useful for tools like `git-blame` and `git-bisect`.
Your contribution must apply cleanly to `master` in order to be considered
mergeable. You may want to regularly [rebase your changes][reba] onto `master`
in order to both clean up any intermediate "development" commits you make and
to ensure that you're up to date.
Your contribution must apply cleanly to `develop` in order to be considered
mergeable. You may want to regularly [rebase your changes][reba] onto
`develop` in order to both clean up any intermediate "development" commits you
make and to ensure that you're up to date.
If you're making a GitHub pull request, it's good practice to make it from a
topic branch, rather than `master`, on your fork.
### Pull Requests and Merges
### Pills
When your work is ready for review, open a pull request, making sure to link to
the tracking issue in the description, which should be formatted as follows
(where `<N>` is the number of this work's tracking issue):
```
### Description
Resolves #<N>.
Thoroughly describe the changes made.
### Related
Reference any related issues, links, papers, etc. here.
```
Tests will run automatically via GitHub Actions when you open a pull request or
push new commits to an existing pull request.
Once you've collected and addressed feedback, tests are passing, and your PR has
been approved, merge the pull request.
**Note**: If you are merging into develop, you *must* be syncing OTAs from
`~binnec-dozzod-marzod` which gets the tip of develop deployed to it. If
your merge breaks `binnec` it's your responsibility to alert people and
fix it. Your PR is shipped when it's successfully been deployed to
`~binnec` and picked up by your personal ship. If you're merging on behalf
of an external developer, this is also your responsibility.
If you properly included the "Resolves
#N." directive in the pull request description, merging will automatically close
the tracking issue associated with the pull request.
## Code style
Hoon will be a less familiar language to many contributors. We've published
some [style guidelines for Hoon][hoon], but above all you should try to mimic
the style of the code around you. With regards to the style used throughout the
codebase: the more recently the code was written, the more standard and accepted
its style is likely to be.
### Kernel Development and Pills
Urbit bootstraps itself from a pill (you can see it being fetched from
`bootstrap.urbit.org` on boot). This is the compiled version of the kernel
(which you can find in the `sys` directory of [Arvo][arvo]), along with a
complete copy of the Arvo source.
You can find the latest solid pill, as well as the latest so-called *brass*
and *ivory* pills, in the `bin/` directory at the repository root.
Any contribution that touches the kernel (i.e., anything in `pkg/arvo/sys`),
should be accompanied by an updated [solid pill](#the-kernel-and-pills). Pills
are tracked in the repository via [git LFS][git-lfs].
Whenever you make a contribution to the kernel, please create a new solid pill
via:
```
sh/update-solid-pill
$ git lfs init
$ git lfs pull
```
and include it along with your contribution.
[git-lfs]: https://git-lfs.github.com
Historically, we've sometimes included these updated pills in separate,
standalone commits (you will see plenty of "pills: update solid" and similar
commits if you look through the history), but this practice is considered to be
deprecated -- you should usually just include the updated pill in the same
commit that updates the source.
## Releases
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
its way onto the network pretty rapidly.
If you want to propose a hotfix (i.e. a small, OTA-updateable change, usually a
bugfix, to some currently-deployed release) then simply make it clear that your
contribution -- whether it be a pull request, patch, or whatever -- is intended
to be a hotfix. A maintainer can then deploy it to the network outside of the
normal release schedule.
Less frequently we release new Vere versions, which requires users to download
new binaries, and occasionally, while Urbit is still in early development, we
breach network continuity in order to release large changes that are difficult
to push out over-the-air. Contributions to Vere, or non-OTA-able updates to
Arvo, will find their way into releases before terribly long.
## Code style
The Urbit project uses two-space indentation and avoids tab characters.
In C code, it should not be too difficult to mimic the style of the code
around you, which is just fairly standard K&R with braces on every
compound statement. One thing to watch out for is top-level sections in
source files that are denoted by comments and are actually indented one
level.
Hoon will be a less familiar language to many contributors. We've published
some [style guidelines for Hoon][hoon], but above all you should try to mimic
the style of the code around you. With regards to the style used throughout
the codebase: the more recently the code was written, the more standard and
accepted its style is likely to be.
## Kernel development
Working on either C or non-kernel Hoon should not bring any surprises, but the
Hoon kernel (anything under [`pkg/arvo/sys/`][sys]) is bootstrapped from a
so-called *pill*, and must be recompiled if any changes are made. This should
happen automatically when you make changes, but if it doesn't, the command to
manually recompile and install the new kernel is `|reset` in `dojo`. This
rebuilds from the `sys` directory in the `base` desk in `%clay`.
Currently, `|reset` does not reload apps like `dojo` itself, which will still
reference the old kernel. To force them to reload, make a trivial edit to their
main source file (under the `app` directory) in `%clay`.
[arvo]: https://github.com/urbit/urbit/tree/master/pkg/arvo
[sys]: https://github.com/urbit/urbit/tree/master/pkg/arvo/sys
## The kernel and pills
Urbit bootstraps itself using a binary blob called a pill (you can see it being
fetched from `bootstrap.urbit.org` on boot). This is the compiled version of
the kernel (which you can find in the `sys` directory of [Arvo][arvo]), along
with a complete copy of the Arvo source.
The procedure for creating a pill is often called "soliding." It is somewhat
similar to `|reset`, but instead of replacing your running kernel, it writes
the compiled kernel to a file. The command to solid is:
The +solid command is used to write the compiled kernel to a file.
```
> .urbit/pill +solid
```
When the compilation finishes, your pill will be found in the
`[pier]/.urb/put/` directory as `urbit.pill`.
When the compilation finishes, your pill will be found in the `[pier]/.urb/put/`
directory as `urbit.pill`.
You can boot a new ship from your local pill with `-B`:
@ -253,48 +192,57 @@ Release pills, i.e. those corresponding to vere releases, are cached at
`https://bootstrap.urbit.org` and are indexed by the vere version number, e.g.
`urbit-0.8.2.pill`.
Pills are also cached in version control via [git LFS][git-lfs]. You can find
the latest solid pill, as well as the latest so-called *brass* and *ivory*
pills, in the `bin/` directory at the repository root. Note that you'll need
to initialise git LFS in order to check these pills out:
Whenever you make a contribution to the kernel, please create a new solid pill
via:
```
$ git lfs init
$ git lfs pull
sh/update-solid-pill
```
[git-lfs]: https://git-lfs.github.com
You should include the updated pill in the same commit that updates the source.
## Issues
## Development Environment
The [GitHub tracker][issu] is our canonical source of truth around issues,
bugs, performance problems, feature requests, and so on. If you encounter any
issues when developing on Urbit, feel free to submit a report about it here.
Although you likely have an identity on the live network, developing on the live
network is high-risk and largely unnecessary. Instead, standard practice is to
work on a fake ship. Fake ships use deterministic keys derived from the ship's
address, don't communicate on the live network, and can communicate with other
fake ships over the local loopback.
A good bug report, description of a crash, etc., should ideally be
*reproducible*, with clear steps as to how another developer can replicate and
examine your problem. That said, this isn't always possible -- some bugs
depend on having created a complicated or unusual state, or can otherwise
simply be difficult to trigger again (say, you encountered it in the last
continuity era).
### Boot a New Fake Ship
Your issue should thus at a minimum be *informative*. The best advice here is
probably "don't write bad issues," where "bad" is a matter of judgment and
taste. Issues that the maintainers don't judge to be sufficiently useful or
informative may be closed.
To boot a new fake ship, pass the `-F` flag and a valid Urbit ship name to
`urbit`:
Feature requests are welcome, but they should include sufficient detail and
explanation, as well as a discussion of perceived benefits one could expect
from them. "It would be cool if.." probably does not, in itself, constitute a
good feature request; instead, try to be specific about what you're requesting,
and what your desired feature would accomplish.
```console
$ bazel build :urbit
$ ln -s bazel-bin/pkg/vere/urbit urbit
$ ./urbit -F <ship>
```
## Staying in touch
By default, booting a fake ship will use the same pill that livenet ships use,
which leads to a non-trivial boot time on the order of tens of minutes. However,
using a development specific "solid" pill reduces this time to a couple minutes.
To boot using the solid pill, download or create one as described in the Kernel
Development and Pills section above and then run the following:
```console
$ ./urbit -F <ship> -B solid.pill
```
### Launch an Existing Fake Ship
To launch an existing fake ship, supply the pier (the ship directory), which is
simply the name of the ship[^1], to `urbit`:
```console
$ ./urbit <ship>
```
[^1]: Unless you specified the pier name using the `-c` flag.
Questions or other communications about contributing to Urbit can go to
[support@urbit.org][mail].
[mail]: mailto:support@urbit.org
[list]: https://groups.google.com/a/urbit.org/forum/#!forum/dev
[repo]: https://github.com/urbit/urbit
[reba]: https://git-rebase.io/

369
MAINTAINERS.md
View File

@ -1,238 +1,79 @@
# Maintainers' Guide
# Maintaining
## Branch organization
## Overview
The essence of this branching scheme is that you create "release branches" of
independently releasable units of work. These can then be released by their
maintainers when ready.
We use a three-stage release pipeline. Each stage of the release pipeline has
its own dedicated branch and corresponding testing moon. 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.
### Master branch
## Branches and Moons
Master is what's released on the network. Deployment instructions are in the
next section, but tagged releases should always come from this branch.
The branches and their corresponding moons that comprise the stages of the
release pipeline are:
### Feature branches
----------------------------------------------------------------------------------------------
Branch | Moon | Target audience | Contains
----------------------------------------------------------------------------------------------
`develop` | `~binnec-dozzod-marzod` | Kernel developers | Latest `develop` branch commit
`release` | `~marnec-dozzod-marzod` | Early Adopters | Latest `release` branch commit
`release` | `~doznec-dozzod-marzod` | App Developers | Latest release candidate
`master` | `~zod` | Everyone else | Latest release
Anyone can create feature branches. For those with commit access to
urbit/urbit, you're welcome to create them in this repo; otherwise, fork the
repo and create them there.
**WARNING**: If you lack the requisite skills to troubleshoot and fix kernel issues, you should not sync from develop/~binnec. If you're not prepared to breach your ship in response to an issue stemming from an early release, do not use pre-release moons.
Usually, new development should start from master, but if your work depends on
work in another feature branch or release branch, start from there.
If, after starting your work, you need changes that are in master, merge it into
your branch. If you need changes that are in a release branch or feature
branch, merge it into your branch, but understand that your work now depends on
that release branch, which means it won't be released until that one is
released.
### Release branches
Release branches are code that is ready to release. All release branch names
should start with `next/`.
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.
Create new release branches as needed. You don't need a new one for every PR,
since many changes are relatively small and can be merged together with little
risk. However, once you merge two branches, they're now coupled and will only
be released together -- unless one of the underlying commits is separately put
on a release branch.
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
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
userspace app, and you put it in `next/landscape`. Separately, you make a small
JS change. If you PR it to `next/landscape`, then it will only be released at
the same time as the app changes. Maybe this is fine, or maybe you want this
change to go out quickly, and the change in `next/landscape` is relatively
risky, so you don't want to push it out on Friday afternoon. In this case, put
the change in another release branch, say `next/js`. Now either can be released
independently.
Suppose you do further work that you want to PR to `next/landscape`, but it
depends on your fixes in `next/js`. Simply merge `next/js` into either your
feature branch or `next/landscape` and PR your finished work to
`next/landscape`. Now there is a one-way coupling: `next/landscape` contains
`next/js`, so releasing it will implicitly release `next/js`. However, you can
still release `next/js` independently.
This scheme extends to other branches, like `next/base` or `next/os1.1` or
`next/ford-fusion`. Some branches may be long-lived and represent simply the
"next" release of something, while others will have a definite lifetime that
corresponds to development of a particular feature or numbered release.
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
branch.
When cutting a new release, you can filter branches with `git branch --list
'next/*'` or by typing "next/" in the branch filter on Github. This will give
you the list of branches which have passed review and may be merged to master
and released. When choosing which branches to release, make sure you understand
the risks of releasing them immediately. If merging these produces nontrivial
conflicts, consider asking the developers on those branches to merge between
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
another.
#### Standard release branches
While you can always create non-standard release branches to stage for a
particular release, most changes should go through the following:
- next/base -- changes to the %base desk in pkg/arvo
- next/garden -- changes to the %garden desk
- next/landscape -- changes to the %landscape desk
- next/bitcoin -- changes to the %bitcoin desk
- next/webterm -- changes to the %webterm desk
- next/vere -- changes to the runtime
### Other cases
Outside contributors can generally target their PRs against master unless
specifically instructed. Maintainers should retarget those branches as
appropriate.
If a commit is not something that goes into a release (eg changes to README or
CI), it may be committed straight to master.
If a hotfix is urgent, it may be PR'd straight to master. This should only be
done if you reasonably expect that it will be released soon and before anything
else is released.
If a series of commits that you want to release is on a release branch, but you
really don't want to release the whole branch, you must cherry-pick them onto
another release branch. Cherry-picking isn't ideal because those commits will
be duplicated in the history, but it won't have any serious side effects.
## Hotfixes
Here lies an informal guide for making hotfix releases and deploying them to
the network.
Take [this 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 how 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 should avoid merging the PR in GitHub directly. Instead, use the
`sh/merge-with-custom-msg` script -- it will produce a merge commit with
message along the lines of:
```
Merge branch FOO (#PR_NUM)
* FOO:
bar: ...
baz: ...
Signed-off-by: SIGNER <signer@example.com>
```
We do this as 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).
`sh/merge-with-custom-msg` performs some useful last-minute urbit-specific
checks, as well.
You might want to alias `sh/merge-with-custom-msg` locally, to make it easier
to use. My .git/config contains the following, for example:
```
[alias]
mu = !sh/merge-with-custom-msg
```
so that I can type e.g. `git mu origin/foo 1337`.
### Prepare a release commit
If you're making a Vere release, just play it safe and update all the pills.
To produce multi pills, you will need to set up an environment with the
appropriate desks with the appropriate contents, doing something like the
following (where `> ` denotes an urbit command and `% ` denotes a unix shell
command):
`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
> |merge %garden our %base
> |merge %landscape our %base
> |merge %bitcoin our %base
> |merge %webterm our %base
> |mount %
> |mount %garden
> |mount %landscape
> |mount %bitcoin
> |mount %webterm
% rsync -avL --delete pkg/arvo/ zod/base/
% rm -rf zod/base/tests/
% for desk in garden landscape bitcoin webterm; do \
rsync -avL --delete pkg/$desk/ zod/$desk/ \
done
> |commit %base
> |commit %garden
> |commit %landscape
> |commit %bitcoin
> |commit %webterm
> .multi/pill +solid %base %garden %landscape %bitcoin %webterm
> .multi-brass/pill +brass %base %garden %landscape %bitcoin %webterm
feature branch ----> develop ----> release ---------> master
| | |
deployed to deployed to deployed to
~binnec moon ~marnec/~doznec moon network
```
And then of course:
If an issue arises in the course of testing the `release` branch (because more
people are using `marnec` than `binnec`), 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.
```console
> .solid/pill +solid
> .brass/pill +brass
> .ivory/pill +ivory
```
## Release Workflow
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
artifacts from pkg/interface and a new version number in the desk.docket-0 of
any desk which changed. If neither the pill nor the JS need to be updated (e.g
if the pill was already updated in the previous merge commit), consider making
the release commit with --allow-empty.
Developers work on feature branches built against `develop`. While doing this,
they continually merge in changes from `develop` to their feature branch. When
their feature is ready (and they've tested it), they open a pull request. After
code review approval and passing tests, their feature can merge into `develop`.
Every merge into `develop` immediately triggers a deploy to the `binnec` moon.
If your merge breaks `binnec` it's your responsibility to fix it.
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
the pill to have the new files/hash. For most things, it is sufficient to run
`npm install; npm run build:prod` in `pkg/interface`.
Once a week on Tuesday, a `release` branch is cut off of `develop`. This release
gets deployed to `marnec` to be tested for the rest of the week. Any fixes that
have to go into the release can go straight into the release branch. New work
that didn't make the release continues on feature branches against `develop`
(eventually merging there). After initial testing on `marnec`, a release
candidate is tagged and merges into `~doznec` where early adopters and app
developers can pick it up and test or update their apps for a new kelvin. If
it's a new kelvin, we also send an email to urbit-dev with instructions for
testing the breaking changes.
However, if you've made a change to Landscape's JS, then you will need to build
a "glob" and upload it to bootstrap.urbit.org. To do this, run `npm install;
npm run build:prod` in `pkg/interface`, and add the resulting
`pkg/arvo/app/landscape/index.[hash].js` to a fakezod at that path (or just create a
new fakezod with `urbit -F zod -B bin/solid.pill -A pkg/arvo`). Run
`:glob|make`, and this will output a file in `fakezod/.urb/put/glob-0vXXX.glob`.
Then on the next Tuesday the release branch merges into master and tagged using
the tag instructions below, we create a GitHub release (marked latest) using
that tag on `master` which documents the changes that went into the release. In
the Github UI you can get the changelog by selecting the tag prior to it from
the previous release when creating the new release. Then the release is deployed
to the broader network via `zod`. Master is then merged back into `develop`
where any fixes that went straight to release get picked up. Lastly, a new
release branch is cut from `develop` and the process begins again.
Upload this file to bootstrap.urbit.org, and modify `+hash` at the top of
`pkg/arvo/app/glob.hoon` to match the hash in the filename of the `.glob` file.
Amend `pkg/arvo/app/landscape/index.html` to import the hashed JS bundle, instead
of the unversioned index.js. Do not commit the produced `index.js` and
make sure it doesn't end up in your pills (they should be less than 10MB each).
### Tag the resulting commit
What you should do here depends on the type of release being made.
First, for Urbit OS releases:
### Tagging
If it's a very trivial hotfix that you know isn't going to break anything, tag
it as `urbit-os-vx.y`. Here 'x' is the major version and 'y' is an OTA patch
counter. Change `urbit-os` to e.g. `landscape` or another desk if that's what you're
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).
counter.
Use an annotated tag, i.e.
@ -256,99 +97,9 @@ Contributions:
[..]
```
You can get the "contributions" section by the shortlog between the
last release and this release:
You can get the "contributions" section by the shortlog between the last release
and this release:
```
git shortlog LAST_RELEASE..
git shortlog --no-merges LAST_RELEASE..
```
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. `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
`urbit-os-vx.y`.
For Vere releases:
Tag the release as `urbit-vx.y`. The tag format should look something like
this:
```
urbit-vx.y
Note that this Vere release will by default boot fresh ships using an Urbit OS
va.b.c pill.
Release binaries:
(linux64)
https://bootstrap.urbit.org/urbit-vx.y-linux64.tgz
(macOS)
https://bootstrap.urbit.org/urbit-vx.y-darwin.tgz
Release notes:
[..]
Contributions:
[..]
```
Ensure the Vere release is marked as the 'latest' release and upload the two
`.tgz` files to the release as `darwin.tgz` and `linux64.tgz`;
this allows us to programmatically retrieve the latest release at
[urbit.org/install/mac/latest/](https://urbit.org/install/mac/latest) and
[urbit.org/install/linux64/latest](https://urbit.org/install/linux64/latest),
respectively.
The same schpeel re: release candidates applies here.
Note that the release notes indicate which version of Urbit OS the Vere release
will use by default when booting fresh ships. 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
separate releases.
### Deploy the update
(**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 should be merged into /~zod/kids and then propagated through other galaxies
and stars to the rest of the network.
For consistency, I create a release tarball and then rsync the files in.
```
$ wget https://github.com/urbit/urbit/archive/urbit-os-vx.y.tar.gz
$ tar xzf urbit-os-vx.y.tar.gz
$ herb zod -p hood -d "+hood/mount /=base="
$ rsync -zr --delete urbit-urbit-os-vx.y/pkg/arvo/ zod/base
$ herb zod -p hood -d "+hood/commit %base"
$ herb zod -p hood -d "+hood/merge %kids our %base"
```
For Vere updates, this means simply 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 %cz hash (for Urbit OS releases) and the release binary
URLs (for Vere releases). Check the urbit-dev archives for examples of these
announcements.
Post the same announcement to the group feed of Urbit Community.

97
README.md
View File

@ -7,101 +7,36 @@ has an identity layer (Azimuth), virtual machine (Vere), and operating system
A running Urbit "ship" is designed to operate with other ships peer-to-peer.
Urbit is a general-purpose, peer-to-peer computer and network.
This repository contains:
This repository contains the [Arvo Kernel][arvo]
- The [Arvo OS][arvo]
- [herb][herb], a tool for Unix control of an Urbit ship
- Source code for [Landscape's web interface][land]
- Source code for the [vere][vere] virtual machine.
For more on the identity layer, see [Azimuth][azim]. To manage your Urbit
identity, use [Bridge][brid].
[arvo]: https://github.com/urbit/urbit/tree/master/pkg/arvo
[azim]: https://github.com/urbit/azimuth
[brid]: https://github.com/urbit/bridge
[herb]: https://github.com/urbit/urbit/tree/master/pkg/herb
[land]: https://github.com/urbit/urbit/tree/master/pkg/interface
[vere]: https://github.com/urbit/urbit/tree/master/pkg/urbit
For the Runtime, see [Vere][vere].
For more on the identity layer, see [Azimuth][azim].
To manage your Urbit identity, use [Bridge][brid].
## Install
To install and run Urbit, please follow the instructions at
[urbit.org/install][start]. You'll be on the live network in a
[urbit.org/getting-started][start]. You'll be on the live network in a
few minutes.
If you're interested in Urbit development, keep reading.
[start]: https://urbit.org/install/
## Development
[![License][license-badge]][license]
[![Build][build-badge]][build]
[![Nix][nix-badge]][nix]
[![Cachix][cachix-badge]][cachix]
Urbit uses [Nix][nix] to manage builds. On Linux and macOS you can install Nix
via:
```
curl -L https://nixos.org/nix/install | sh
```
You can optionally setup Nix to pull build artefacts from the binary cache
that continuous integration uses. This will improve build times and avoid
unnecessary recompilations of common dependencies. Once Nix has been installed
you can setup Cachix via:
```
nix-env -iA cachix -f https://cachix.org/api/v1/install
cachix use ares
```
The Makefile in the project's root directory contains useful phony targets for
building, installing, testing, and so on. You can use it to avoid dealing with
Nix explicitly.
To build the Urbit virtual machine binary, for example, use:
```
make build
```
The test suite can similarly be run via a simple:
```
make test
```
Note that some of the Makefile targets need access to pills tracked via [git
LFS][git-lfs], so you'll also need to have those available locally:
```
git lfs install
git lfs pull
```
[license]: https://raw.githubusercontent.com/urbit/urbit/master/LICENSE.txt
[license-badge]: https://img.shields.io/badge/license-MIT-blue.svg
[build]: https://github.com/urbit/urbit/actions
[build-badge]: https://github.com/urbit/urbit/workflows/build/badge.svg
[cachix]: https://ares.cachix.org
[cachix-badge]: https://img.shields.io/badge/cachix-ares-purple.svg
[nix]: https://nixos.org
[nix-badge]: https://img.shields.io/badge/builtwith-nix-purple.svg
[git-lfs]: https://git-lfs.github.com
[start]: https://urbit.org/getting-started/
## Contributing
Contributions of any form are more than welcome! Please take a look at our
[contributing guidelines][cont] for details on our git practices, coding
styles, how we manage issues, and so on.
For instructions on contributing to Landscape, see [its][lcont] guidelines.
styles, and how we manage issues.
You might also be interested in joining the [urbit-dev][list] mailing list.
## Release
For details about our release process, see the [maintainers guidelines][main]
[arvo]: https://github.com/urbit/urbit/tree/master/pkg/arvo
[azim]: https://github.com/urbit/azimuth
[brid]: https://github.com/urbit/bridge
[vere]: https://github.com/urbit/vere
[list]: https://groups.google.com/a/urbit.org/forum/#!forum/dev
[cont]: https://github.com/urbit/urbit/blob/master/CONTRIBUTING.md
[lcont]: https://github.com/urbit/urbit/blob/master/pkg/interface/CONTRIBUTING.md
[main]: https://github.com/urbit/urbit/blob/master/MAINTAINERS.md