ilyakooo0/urbit
1
0
Fork 0
mirror of https://github.com/ilyakooo0/urbit.git synced 2024-09-11 10:46:43 +03:00
Code Issues Packages Projects Releases Wiki Activity

updates CONTRIBUTING.md, removing obsolete instructions

Browse Source
This commit is contained in:
Joe Bryan 2019-01-15 16:03:37 -05:00
parent fac0fef804
commit c0138ad0d3
1 changed files with 81 additions and 94 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

175
CONTRIBUTING.md
View File

@ -2,49 +2,35 @@
Thank you for your interest in contributing to urbit. 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 You may have an identity on the live network, but doing all your
development on the live network would be cumbersome and unnecessary. development on the live network would be cumbersome and unnecessary.
Standard practice in urbit development is to work on a fake `~zod`. A Standard practice in urbit development is to work on a fake `~zod`.
fake `~zod` will get its initial files from a directory you specify Fake ships use deterministic keys (derived from the ship address)
rather than trying to sync them over the network, which is invaluable and don't talk to the live network. They can talk to each other over
for working in Hoon. Also, a fake `~zod` or any fake urbit instances you the local loopback.
start do not talk to the live network, but to a fake network that exists
only on your computer.
First, you'll want to check out the Arvo repository. Arvo is kept in its To start a fake ship, simply specify the name with `-F`:
own repository, and changes more rapidly than the main C project does.
git clone https://github.com/urbit/arvo ```
$ urbit -F zod
```
The arvo repository can live safely inside the main urbit repository if You can also pass a name for the *pier* (or ship directory):
you want, since it's listed in .gitignore. However, vere will use the
path you specify on the command line with the `-A` option.
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 $ urbit fake-zod/
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.
## Git practice ## 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: 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" And, additionally, fork the repository on GitHub by clicking the "Fork"
button. Add your fork as a remote: 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: 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 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 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, latest tagged release as your starting point. For other repositories,
anywhere pointed to by `master` is alright to start from. 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 Now you are free to do your work on this branch. When finished, you may
want to clean up your commits: 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 Then you can push to your public fork with `git push` and make a pull
request via the GitHub UI. 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 source files that are denoted by comments and are actually indented one
level. level.
Hoon will be a less familiar language to many contributors. Some of our Hoon will be a less familiar language to many contributors. More details
less obvious stylistic rules are: 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 ## Kernel development
developers use 80 character terminals/tmux panes/&c.
- Tab characters are actually a syntax error, so be extra sure your Working on either C or non-kernel Hoon should not bring any surprises, but
editor is not inserting any. Trailing whitespace is *usually* not a the Hoon kernel (anything under `sys/` in [urbit/arvo](https://github.com/urbit/arvo))
syntax error, but avoiding it is encouraged. is bootstrapped from `urbit.pill`, and must be recompiled if any changes are
- The kernel convention is that line comments start at column 57 with made. This should happen automatically when you make changes, but if it doesn't,
the `::` followed by 2 spaces. This leaves 20 characters for the the command to manually recompile the kernel and install the new kernel
comment. Outside the kernel, things are less strict. is `|reset` in `dojo`. This rebuilds from the `sys` directory in the
- Tall arms within a core are conventionally separated by empty comments `home` desk in `%clay`. Currently, `|reset` does not reload apps like
(just `::`) at the same indentation level as the initial `++` or `+-`. `dojo` itself, which will still reference the old kernel. To force them
The last arm in a core is not followed by an empty comment, because it to reload, make a trivial edit to their main source file (under the
is visually closed by the `--` that closes the core. The empty comment `app` directory) in `%clay`.
is also sometimes omitted in data structure definitions.
## The kernel and pills ## The kernel and pills
urbit bootstraps itself using a binary blob called `urbit.pill`. You urbit bootstraps itself using a binary blob called `urbit.pill`. You
probably remember it being fetched from `bootstrap.urbit.org` before probably remember it being fetched from `bootstrap.urbit.org` before
your first boot. This is just the compiled version of the kernel, which your first boot. This is the compiled version of the kernel (which
you can find in the `arvo/arvo/` directory - `hoon.hoon`, `zuse.hoon`, you can find in the `sys` directory of [urbit/arvo](https://github.com/urbit/arvo)),
and so on. along with a complete copy of the Arvo repository as source.
The procedure for creating `urbit.pill` is often called "soliding". It The procedure for creating `urbit.pill` is often called "soliding". It
is somewhat similar to `|reset`, but instead of replacing your running is somewhat similar to `|reset`, but instead of replacing your running
kernel, it writes the compiled kernel to a file. The command to solid 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 When the compilation finishes, your `urbit.pill` will be found in the
`[pier]/.urb/put/` directory. `[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 Ordinarily, `http://bootstrap.urbit.org/latest.pill` will be updated
to match whatever's on `master` in the `arvo` repository with every 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 merge to `master`. Older pills will be stored with the first 10
relevant commit as `[sha1].pill`. 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 The continuous-integration build of the `urbit/arvo` repository
pills for your branch, please include them with your pull request, and uploads these pills for any successful build (if the commit or pull-request
they'll be uploaded to `bootstrap.urbit.org` when your branch is merged. 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`: ```
$ git clone https://github.com/urbit/arvo
(If you've already built urbit first run `make clean`.) $ urbit -F zod -A path/to/arvo -s fake-zod
```
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 ## What to work on
@ -180,12 +169,10 @@ eager to have outside contributions on. Check here first!
## Staying in touch ## Staying in touch
The urbit developers communicate on urbit itself. Joining the The urbit developers communicate on urbit itself. Joining the
`urbit-meta` channel on `talk` is highly recommended, as is reading the `urbit-meta` channel on
forums at [http://urbit.org/fora](http://urbit.org/fora). Subscribing to [`:talk`](https://urbit.org/docs/learn/arvo/arvo-internals/messaging/)
`urbit-dev` on Google Groups is also recommended, since this is where is highly recommended, as is reading the forums at
continuity breach notifications are sent. [http://urbit.org/fora](http://urbit.org/fora).
Pull requests in non-GitHub forms can go to Raymond Pasco Questions or other communications about contributing to Urbit can go to
([ray@the.ug](mailto:ray@the.ug)). Questions or other communications [support@urbit.org](mailto:support@urbit.org).
about contributing to Urbit can go to Raymond Pasco or Philip Monk
([philip.monk@tlon.io](mailto:philip.monk@tlon.io)).