diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e821af3544..7c4fefd6f5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,49 +2,35 @@ Thank you for your interest in contributing to urbit. -## Fake `~zod`s +See [urbit.org/docs/getting-started](https://urbit.org/docs/getting-started/#arvo) +for basic orientation and usage instructions. + +## Fake ships 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`. A -fake `~zod` will get its initial files from a directory you specify -rather than trying to sync them over the network, which is invaluable -for working in Hoon. Also, a fake `~zod` or any fake urbit instances you -start do not talk to the live network, but to a fake network that exists -only on your computer. +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. -First, you'll want to check out the Arvo repository. Arvo is kept in its -own repository, and changes more rapidly than the main C project does. +To start a fake ship, simply specify the name with `-F`: - git clone https://github.com/urbit/arvo +``` +$ urbit -F zod +``` -The arvo repository can live safely inside the main urbit repository if -you want, since it's listed in .gitignore. However, vere will use the -path you specify on the command line with the `-A` option. +You can also pass a name for the *pier* (or ship directory): -To start a fake `~zod`, the command is: +``` +$ urbit -F zod my-fake-zod +``` - $ urbit -c -F zod -A [arvo checkout] [pier directory] +To resume a fake ship, just pass the name of the pier: -To resume one that was already created, just as on the live network, -remove `-c` and `-A [arvo checkout]` (but leave the rest of the options -there). `-F` uses the fake network. - -## Kernel development - -Working on either C or non-kernel Hoon should not bring any surprises, -but the Hoon kernel (anything under `arvo/arvo/`) is bootstrapped -from `urbit.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 the kernel and install the new kernel -is `|reset` in `dojo`. This rebuilds from the `arvo` directory in the -`home` 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`. - -If you do any kernel development, be sure to read the section below about -pills. +``` +$ urbit fake-zod/ +``` ## Git practice @@ -54,16 +40,22 @@ what you are doing, skip down to the Style section. Start by cloning the repository on your work machine: - git clone https://github.com/urbit/urbit +``` +$ git clone https://github.com/urbit/urbit +``` And, additionally, fork the repository on GitHub by clicking the "Fork" button. Add your fork as a remote: - git remote add [username] https://github.com/[username]/urbit +``` +$ git remote add [username] https://github.com/[username]/urbit +``` and set it as the default remote to push to: - git config --local remote.pushDefault [username] +``` +$ git config --local remote.pushDefault [username] +``` This is good practice for any project that uses git. You will pull upstream branches from urbit/urbit and push to your personal urbit fork @@ -73,12 +65,16 @@ Next, start a new branch to do your work on. For `urbit`, please use the latest tagged release as your starting point. For other repositories, anywhere pointed to by `master` is alright to start from. - git checkout -b [branch name] [starting point] +``` +$ git checkout -b [branch name] [starting point] +``` Now you are free to do your work on this branch. When finished, you may want to clean up your commits: - git rebase -i [starting point] +``` +$ git rebase -i [starting point] +``` Then you can push to your public fork with `git push` and make a pull request via the GitHub UI. @@ -96,73 +92,66 @@ 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. Some of our -less obvious stylistic rules are: +Hoon will be a less familiar language to many contributors. More details +are forthcoming; for now, the `%ford` vane (in +[`sys/vane/ford.hoon`](https://github.com/urbit/arvo/blob/master/sys/vane/ford.hoon)) +is the highest quality code in the kernel. -- Keep your source files 80 characters or less wide. Many urbit - developers use 80 character terminals/tmux panes/&c. -- Tab characters are actually a syntax error, so be extra sure your - editor is not inserting any. Trailing whitespace is *usually* not a - syntax error, but avoiding it is encouraged. -- The kernel convention is that line comments start at column 57 with - the `::` followed by 2 spaces. This leaves 20 characters for the - comment. Outside the kernel, things are less strict. -- Tall arms within a core are conventionally separated by empty comments - (just `::`) at the same indentation level as the initial `++` or `+-`. - The last arm in a core is not followed by an empty comment, because it - is visually closed by the `--` that closes the core. The empty comment - is also sometimes omitted in data structure definitions. +## Kernel development + +Working on either C or non-kernel Hoon should not bring any surprises, but +the Hoon kernel (anything under `sys/` in [urbit/arvo](https://github.com/urbit/arvo)) +is bootstrapped from `urbit.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 the kernel and install the new kernel +is `|reset` in `dojo`. This rebuilds from the `sys` directory in the +`home` 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`. ## The kernel and pills urbit bootstraps itself using a binary blob called `urbit.pill`. You probably remember it being fetched from `bootstrap.urbit.org` before -your first boot. This is just the compiled version of the kernel, which -you can find in the `arvo/arvo/` directory - `hoon.hoon`, `zuse.hoon`, -and so on. +your first boot. This is the compiled version of the kernel (which +you can find in the `sys` directory of [urbit/arvo](https://github.com/urbit/arvo)), +along with a complete copy of the Arvo repository as source. The procedure for creating `urbit.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, on a fakezod: +is: - .urbit/pill +solid +``` +> .urbit/pill +solid +``` When the compilation finishes, your `urbit.pill` will be found in the `[pier]/.urb/put/` directory. +You can boot a new ship from your local pill with `-B`: + +``` +$ urbit -F zod -B path/to/urbit.pill fake-zod +``` + Ordinarily, `http://bootstrap.urbit.org/latest.pill` will be updated to match whatever's on `master` in the `arvo` repository with every -merge to `master`. Older pills will be stored with the `git` SHA1 of the -relevant commit as `[sha1].pill`. +merge to `master`. Older pills will be stored with the first 10 +characters of the `git` SHA1 of the relevant commit as `git-[sha1].pill`. -If you're doing heavy kernel hacking and want to submit intermediate -pills for your branch, please include them with your pull request, and -they'll be uploaded to `bootstrap.urbit.org` when your branch is merged. +The continuous-integration build of the `urbit/arvo` repository +uploads these pills for any successful build (if the commit or pull-request +affects the `sys/` directory). -## Debug urbit with `gdb` +You can boot from one of these pills by passing the path to an Arvo +working copy with `-A` (and `-s` for *search*): -Follow the build instructions in README.md but run `make` with argument `DEBUG=yes`: - -(If you've already built urbit first run `make clean`.) - - make DEBUG=yes - -Run `gdb`, while loading `bin/urbit` and its symbol table: - - gdb bin/urbit - -Set a breakpoint on `main()` (optional): - - break main - -Run your urbit comet `mycomet`: - - run mycomet - -Continue from the breakpoint on `main()`: - - continue +``` +$ git clone https://github.com/urbit/arvo +$ urbit -F zod -A path/to/arvo -s fake-zod +``` ## What to work on @@ -180,12 +169,10 @@ eager to have outside contributions on. Check here first! ## Staying in touch The urbit developers communicate on urbit itself. Joining the -`urbit-meta` channel on `talk` is highly recommended, as is reading the -forums at [http://urbit.org/fora](http://urbit.org/fora). Subscribing to -`urbit-dev` on Google Groups is also recommended, since this is where -continuity breach notifications are sent. +`urbit-meta` channel on +[`:talk`](https://urbit.org/docs/learn/arvo/arvo-internals/messaging/) +is highly recommended, as is reading the forums at +[http://urbit.org/fora](http://urbit.org/fora). -Pull requests in non-GitHub forms can go to Raymond Pasco -([ray@the.ug](mailto:ray@the.ug)). Questions or other communications -about contributing to Urbit can go to Raymond Pasco or Philip Monk -([philip.monk@tlon.io](mailto:philip.monk@tlon.io)). +Questions or other communications about contributing to Urbit can go to +[support@urbit.org](mailto:support@urbit.org).