diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e1f66402b..7724d31fd 100644 --- a/CONTRIBUTING.md +++ b/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//<...>`, where `` 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/` 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 `` is the number of this work's tracking issue): ``` -sh/update-solid-pill +### Description + +Resolves #. + +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 +``` + +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 -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 `/.urb/put/urbit.pill` (note that `` is +the ship directory), which you can then use to boot a new ship: + +```console +$ ./urbit -F -B /.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 +``` + +[^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/ diff --git a/MAINTAINERS.md b/MAINTAINERS.md index 29370a874..ec0fdf8dc 100644 --- a/MAINTAINERS.md +++ b/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 -``` - -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.. -``` - -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. +git shortlog LAST_RELEASE.. --no-merges +``` \ No newline at end of file diff --git a/README.md b/README.md index d8b6a3d28..29306d32d 100644 --- a/README.md +++ b/README.md @@ -7,101 +7,39 @@ 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 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/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 \ No newline at end of file