mirror of
https://github.com/ilyakooo0/urbit.git
synced 2024-09-11 10:46:43 +03:00
updates CONTRIBUTING.md, removing obsolete instructions
This commit is contained in:
parent
fac0fef804
commit
c0138ad0d3
175
CONTRIBUTING.md
175
CONTRIBUTING.md
@ -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)).
|
|
||||||
|
Loading…
Reference in New Issue
Block a user