mirror of
https://github.com/ilyakooo0/urbit.git
synced 2024-09-11 10:46:43 +03:00
docs: update current release processes
issue: https://github.com/urbit/urbit/issues/6198 maintainers: explain the new release process contributing: explain kernel releases and issue/PR requirements readme: simplify and direct to relevant docs
This commit is contained in:
parent
d8ca6063af
commit
a544cd17f4
385
CONTRIBUTING.md
385
CONTRIBUTING.md
@ -1,141 +1,95 @@
|
||||
# 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.
|
||||
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 +98,56 @@ 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
|
||||
|
||||
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:
|
||||
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):
|
||||
|
||||
```
|
||||
sh/update-solid-pill
|
||||
### Description
|
||||
|
||||
Resolves #<N>.
|
||||
|
||||
Thoroughly describe the changes made.
|
||||
|
||||
### Related
|
||||
|
||||
Reference any related issues, links, papers, etc. here.
|
||||
```
|
||||
|
||||
and include it along with your contribution.
|
||||
Tests will run automatically via GitHub Actions when you open a pull request or
|
||||
push new commits to an existing pull request.
|
||||
|
||||
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.
|
||||
Once you've collected and addressed feedback, tests are passing, and your PR has
|
||||
been approved, merge the pull request. 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.
|
||||
|
||||
## Releases
|
||||
### Kernel Development and Pills
|
||||
|
||||
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.
|
||||
If you're making changes to the kernel (i.e., anything in `pkg/arvo/sys`) you
|
||||
need to know about pills.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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 procedure for creating a pill is often called "soliding." It writes the
|
||||
compiled kernel to a file. The command to solid is:
|
||||
|
||||
```
|
||||
> .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`:
|
||||
|
||||
@ -255,8 +161,8 @@ Release pills, i.e. those corresponding to vere releases, are cached at
|
||||
|
||||
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:
|
||||
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:
|
||||
|
||||
```
|
||||
$ git lfs init
|
||||
@ -265,36 +171,97 @@ $ git lfs pull
|
||||
|
||||
[git-lfs]: https://git-lfs.github.com
|
||||
|
||||
## Issues
|
||||
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].
|
||||
|
||||
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.
|
||||
Whenever you make a contribution to the kernel, please create a new solid pill
|
||||
via:
|
||||
|
||||
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).
|
||||
```
|
||||
sh/update-solid-pill
|
||||
```
|
||||
|
||||
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.
|
||||
You should include the updated pill in the same commit that updates the source.
|
||||
|
||||
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.
|
||||
Since anything under [`pkg/arvo/sys/`][sys]) is bootstrapped from a pill, it
|
||||
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`.
|
||||
|
||||
## Staying in touch
|
||||
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
|
||||
|
||||
## 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.
|
||||
|
||||
## Development Environment
|
||||
|
||||
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.
|
||||
|
||||
### Boot a New Fake Ship
|
||||
|
||||
To boot a new fake ship, pass the `-F` flag and a valid Urbit ship name to
|
||||
`urbit`:
|
||||
|
||||
```console
|
||||
$ bazel build :urbit
|
||||
$ ln -s bazel-bin/pkg/vere/urbit urbit
|
||||
$ ./urbit -F <ship>
|
||||
```
|
||||
|
||||
By default, booting a fake ship will use the same pre-compiled kernelspace-- a
|
||||
"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 pill-- a "solid"
|
||||
pill-- the time to boot a new fake ship can be reduced to a few minutes.
|
||||
|
||||
The solid pill (and other pills) live in the [Urbit repo][urbit]. To boot using
|
||||
the solid pill, download the pill and then run:
|
||||
|
||||
```console
|
||||
$ ./urbit -F <ship> -B solid.pill
|
||||
```
|
||||
|
||||
Instead of downloading the pill, you can also generate one yourself using
|
||||
[`dojo`][dojo]:
|
||||
|
||||
```console
|
||||
dojo> .urbit/pill +solid
|
||||
```
|
||||
|
||||
This will write the pill to `<pier>/.urb/put/urbit.pill` (note that `<pier>` is
|
||||
the ship directory), which you can then use to boot a new ship:
|
||||
|
||||
```console
|
||||
$ ./urbit -F <another-ship> -B <pier>/.urb/put/urbit.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 specify the pier 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/
|
||||
|
372
MAINTAINERS.md
372
MAINTAINERS.md
@ -1,238 +1,82 @@
|
||||
# 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
|
||||
--------------------------------------------------------------
|
||||
`develop` | `~binnec-dozzod-marzod` | Kernel developers
|
||||
`release` | `~marnec-dozzod-marzod` | Early Adopters
|
||||
`release` | `~doznec-dozzod-marzod` | App Developers
|
||||
`master` | `~zod` | Everyone else
|
||||
|
||||
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.
|
||||
`~binnec` Every commit merged to develop is deployed to `binnec`
|
||||
`~marnec` Every release branch commit is deployed to `marnec`
|
||||
`~doznec` Late stage release candidates go to `~doznec`
|
||||
`zod` `zod` distributes the new kernel to the general public
|
||||
|
||||
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 +100,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 LAST_RELEASE.. --no-merges
|
||||
```
|
||||
|
||||
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.
|
||||
|
96
README.md
96
README.md
@ -7,22 +7,12 @@ 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 Landscape (the UI), see [Garden][gard].
|
||||
For more on the identity layer, see [Azimuth][azim].
|
||||
To manage your Urbit identity, use [Bridge][brid].
|
||||
|
||||
## Install
|
||||
|
||||
@ -30,78 +20,26 @@ To install and run Urbit, please follow the instructions at
|
||||
[urbit.org/install][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
|
||||
|
||||
## 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
|
||||
[herb]: https://github.com/urbit/urbit/tree/master/pkg/herb
|
||||
[vere]: https://github.com/urbit/urbit/tree/master/pkg/urbit
|
||||
[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
|
||||
[gard]: https://github.com/urbit/garden
|
Loading…
Reference in New Issue
Block a user