shrub/CONTRIBUTING.md

Contributing to urbit

Thank you for your interest in contributing to urbit.

Development practice

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 the urb/zod/ directory 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.

To start a fake ~zod, the command is:

bin/urbit -F -I zod -c [pier directory]

To resume one that was already created, just as on the live network, remove -c (but leave the rest of the options there). -F uses the fake network, and -I starts an "imperial" instance - that is, an 8-bit galaxy.

Kernel development

Working on either C or non-kernel Hoon should not bring any surprises, but the Hoon kernel (anything under urb/zod/arvo/) is bootstrapped from urbit.pill in urb/, and must be manually recompiled if any changes are made. 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 ape directory) in %clay.

If you do any kernel development, be sure to read the section below about pills.

Git practice

Since we use the GitHub issue tracker, it is helpful to contribute via a GitHub pull request. If you already know 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

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

and set it as the default remote to push to:

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 by default.

Next, check out test, which is the mainline development branch, and base a new branch on it to do your work on:

git checkout test
git checkout -b [branch name]

Now you are free to do your work on this branch. When finished, you may want to clean up your commits:

git rebase -i test

Then you can push to your public fork with git push and make a pull request via the GitHub UI. Make sure you request to merge your branch into test, not master.

After your changes are merged upstream, you can delete your branch (via github UI or git push :[branch] remotely, and with git branch -d locally).

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. Some of our less obvious stylistic rules are:

• 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.

The kernel and pills

urbit bootstraps itself using a binary blob called urbit.pill, which we do indeed keep in version control. This creates some special requirements. If you are not changing anything in the kernel (everything under urb/zod/arvo/) then you can skim this section (please do not skip it entirely, though). If you are working there, then this section is critically important!

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:

.urbit/pill +solid

When the compilation finishes, your urbit.pill will be found in the [pier]/.urb/put/ directory. Copy it into urb/ and add it to your commit.

The requirement here is that every commit that changes the kernel must come with an urbit.pill built from the same code in urb/zod/arvo/ for that commit. (Only changing the actual Hoon code counts, so a change to a jet with no corresponding Hoon change does not require a new pill.) This is so that checking out an arbitrary revision and starting up a fakezod actually works as expected. However you do this is fine, but I like to do it as part of my committing process - just before git commit, I fire up a new fakezod. This will use the previous urbit.pill, but the kernel code in %clay will be copied from urb/zod/arvo/, so +solid will compile it. Then I copy urbit.pill into urb/ and make my commit.

If you rebase or interactive rebase your commits, be sure to preserve this property on all the commits you end up with. If multiple people were collaborating on your branch, you may end up with conflicts in urbit.pill and have to merge the branch into itself to resolve them. Just do the same procedure to create a new, merged pill before committing the merge. Otherwise, just make sure to use the correct urbit.pill for each commit.

Debug urbit with gdb

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

What to work on

If you are not thinking of contributing with a specific goal in mind, the GitHub issue tracker is the first place you should look for ideas. Issues are tagged with a priority and a difficulty. A good place to start is on either a low-difficulty issue or a low-priority issue. Higher priority issues are likely to be assigned to someone - if this is the case, then contacting that person to coordinate before starting to work is probably a good idea.

There is also a "help wanted" tag for things that we are especially eager to have outside contributions on. Check here first!

Staying in touch

The urbit developers communicate on urbit itself. Joining the ~doznec/urbit-meta channel on talk is highly recommended. Subscribing to urbit-dev on Google Groups is also recommended, since this is where continuity breach notifications are sent.

You can also contact one of the following people:

• Philip Monk

  email: philip.monk@tlon.io

  urbit: ~wictuc-folrex

  GitHub: @philipcmonk

• Raymond Pasco

  email: ray@the.ug

  urbit: ~ramtev-wisbyt

  GitHub: @juped