2023-01-12 20:23:43 +03:00
|
|
|
## Workflow
|
2019-06-17 13:44:08 +03:00
|
|
|
|
2023-01-12 20:23:43 +03:00
|
|
|
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.
|
2019-06-17 13:44:08 +03:00
|
|
|
|
2023-01-12 20:23:43 +03:00
|
|
|
## Issues
|
2019-06-17 13:44:08 +03:00
|
|
|
|
2023-01-12 20:23:43 +03:00
|
|
|
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.
|
2019-06-17 13:44:08 +03:00
|
|
|
|
2023-01-12 20:23:43 +03:00
|
|
|
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.
|
2019-06-17 13:44:08 +03:00
|
|
|
|
2023-01-12 20:23:43 +03:00
|
|
|
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.
|
2019-06-17 13:44:08 +03:00
|
|
|
|
2023-01-12 20:23:43 +03:00
|
|
|
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.
|
2019-10-06 17:57:47 +03:00
|
|
|
|
2023-01-12 20:23:43 +03:00
|
|
|
### Feature Branch Names
|
2019-10-06 17:57:47 +03:00
|
|
|
|
2023-01-12 20:23:43 +03:00
|
|
|
Every branch that you intend to put up for review must adhere to the form
|
|
|
|
`i/<N>/<...>`, where `<N>` 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/<N>` a well-formed branch name. These feature branches should be based
|
|
|
|
off of `develop`.
|
2019-10-06 17:57:47 +03:00
|
|
|
|
2023-01-12 20:23:43 +03:00
|
|
|
### Commits
|
2019-06-17 13:44:08 +03:00
|
|
|
|
2023-01-12 20:23:43 +03:00
|
|
|
Commits should generally be relevant, atomic, and have descriptions formatted in
|
|
|
|
the following manner:
|
2019-06-17 13:44:08 +03:00
|
|
|
|
2019-08-28 18:51:22 +03:00
|
|
|
> component: short description
|
2019-08-28 17:32:44 +03:00
|
|
|
>
|
2019-08-28 18:51:22 +03:00
|
|
|
> long description
|
2019-06-17 13:44:08 +03:00
|
|
|
|
2019-08-28 17:32:44 +03:00
|
|
|
The 'component' is a short prefix of what area of the codebase the commit
|
2023-01-12 20:23:43 +03:00
|
|
|
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, 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.
|
2019-06-17 13:44:08 +03:00
|
|
|
|
2019-11-07 12:14:41 +03:00
|
|
|
Here is an example of our commit format, taken from a commit in the history:
|
2019-06-17 13:44:08 +03:00
|
|
|
|
2019-08-28 17:32:44 +03:00
|
|
|
> zuse: remove superfluous 'scup' and 'culm' types.
|
|
|
|
>
|
|
|
|
> %zuse includes definitions for 'scup' and 'culm', both of which are
|
2023-01-12 20:23:43 +03:00
|
|
|
> 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).
|
2019-08-28 17:32:44 +03:00
|
|
|
>
|
2023-01-12 20:23:43 +03:00
|
|
|
> This commit deletes 'scup' and 'culm' and refactors what little code made use
|
|
|
|
> of them.
|
2019-06-17 13:44:08 +03:00
|
|
|
|
2023-01-12 20:23:43 +03:00
|
|
|
Note that the short description is prefixed by `zuse:`, which is what the commit
|
|
|
|
touches. Otherwise it just includes a summary of the change.
|
2019-11-07 12:14:41 +03:00
|
|
|
|
|
|
|
Here's another example:
|
|
|
|
|
|
|
|
> build: give arvo a high priority
|
|
|
|
>
|
2023-01-12 20:23:43 +03:00
|
|
|
> 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.
|
2019-11-07 12:14:41 +03:00
|
|
|
>
|
|
|
|
> Fixes #1912.
|
|
|
|
|
|
|
|
Note that it cites a previous relevant commit, `0bdced981e4`, in its summary,
|
|
|
|
and also points at the issue that it resolves.
|
|
|
|
|
2019-08-28 17:32:44 +03:00
|
|
|
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
|
|
|
|
level of *code*, not of entire features. You don't have to squash your commits
|
|
|
|
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`.
|
|
|
|
|
2023-01-12 20:23:43 +03:00
|
|
|
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.
|
2019-08-28 17:32:44 +03:00
|
|
|
|
2023-01-12 20:23:43 +03:00
|
|
|
### Pull Requests and Merges
|
2019-08-28 17:32:44 +03:00
|
|
|
|
2023-01-12 20:23:43 +03:00
|
|
|
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 `<N>` is the number of this work's tracking issue):
|
2019-08-28 17:32:44 +03:00
|
|
|
|
2019-06-17 13:44:08 +03:00
|
|
|
```
|
2023-01-12 20:23:43 +03:00
|
|
|
### Description
|
2019-06-17 13:44:08 +03:00
|
|
|
|
2023-01-12 20:23:43 +03:00
|
|
|
Resolves #<N>.
|
2019-06-17 13:44:08 +03:00
|
|
|
|
2023-01-12 20:23:43 +03:00
|
|
|
Thoroughly describe the changes made.
|
2019-08-28 17:32:44 +03:00
|
|
|
|
2023-01-12 20:23:43 +03:00
|
|
|
### Related
|
2019-08-28 17:38:17 +03:00
|
|
|
|
2023-01-12 20:23:43 +03:00
|
|
|
Reference any related issues, links, papers, etc. here.
|
|
|
|
```
|
2019-06-17 13:44:08 +03:00
|
|
|
|
2023-01-12 20:23:43 +03:00
|
|
|
Tests will run automatically via GitHub Actions when you open a pull request or
|
|
|
|
push new commits to an existing pull request.
|
2019-06-17 13:44:08 +03:00
|
|
|
|
2023-01-12 20:23:43 +03:00
|
|
|
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.
|
2019-06-17 13:44:08 +03:00
|
|
|
|
2023-01-12 20:23:43 +03:00
|
|
|
### Kernel Development and Pills
|
2019-06-17 13:44:08 +03:00
|
|
|
|
2023-01-12 20:23:43 +03:00
|
|
|
If you're making changes to the kernel (i.e., anything in `pkg/arvo/sys`) you
|
|
|
|
need to know about pills.
|
2019-06-17 13:44:08 +03:00
|
|
|
|
2023-01-12 20:23:43 +03:00
|
|
|
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.
|
2019-06-17 13:44:08 +03:00
|
|
|
|
2023-01-12 20:23:43 +03:00
|
|
|
The procedure for creating a pill is often called "soliding." It writes the
|
|
|
|
compiled kernel to a file. The command to solid is:
|
2019-06-17 13:44:08 +03:00
|
|
|
|
|
|
|
```
|
|
|
|
> .urbit/pill +solid
|
|
|
|
```
|
|
|
|
|
2023-01-12 20:23:43 +03:00
|
|
|
When the compilation finishes, your pill will be found in the `[pier]/.urb/put/`
|
|
|
|
directory as `urbit.pill`.
|
2019-06-17 13:44:08 +03:00
|
|
|
|
|
|
|
You can boot a new ship from your local pill with `-B`:
|
|
|
|
|
|
|
|
```
|
|
|
|
$ urbit -F zod -B path/to/urbit.pill my-fake-zod
|
|
|
|
```
|
|
|
|
|
2019-08-28 17:46:35 +03:00
|
|
|
Release pills, i.e. those corresponding to vere releases, are cached at
|
|
|
|
`https://bootstrap.urbit.org` and are indexed by the vere version number, e.g.
|
|
|
|
`urbit-0.8.2.pill`.
|
2019-07-15 13:40:53 +03:00
|
|
|
|
|
|
|
Pills are also cached in version control via [git LFS][git-lfs]. You can find
|
2019-08-28 17:46:35 +03:00
|
|
|
the latest solid pill, as well as the latest so-called *brass* and *ivory*
|
2023-01-12 20:23:43 +03:00
|
|
|
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:
|
2019-07-15 13:40:53 +03:00
|
|
|
|
|
|
|
```
|
|
|
|
$ git lfs init
|
|
|
|
$ git lfs pull
|
2019-06-17 13:44:08 +03:00
|
|
|
```
|
|
|
|
|
2019-07-15 13:40:53 +03:00
|
|
|
[git-lfs]: https://git-lfs.github.com
|
|
|
|
|
2023-01-12 20:23:43 +03:00
|
|
|
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].
|
2019-08-28 18:20:09 +03:00
|
|
|
|
2023-01-12 20:23:43 +03:00
|
|
|
Whenever you make a contribution to the kernel, please create a new solid pill
|
|
|
|
via:
|
2019-08-28 18:20:09 +03:00
|
|
|
|
2023-01-12 20:23:43 +03:00
|
|
|
```
|
|
|
|
sh/update-solid-pill
|
|
|
|
```
|
2019-08-28 18:20:09 +03:00
|
|
|
|
2023-01-12 20:23:43 +03:00
|
|
|
You should include the updated pill in the same commit that updates the source.
|
2019-08-28 18:20:09 +03:00
|
|
|
|
2023-01-12 20:23:43 +03:00
|
|
|
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`.
|
|
|
|
|
|
|
|
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 <ship>
|
|
|
|
```
|
|
|
|
|
|
|
|
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 <ship> -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 `<pier>/.urb/put/urbit.pill` (note that `<pier>` is
|
|
|
|
the ship directory), which you can then use to boot a new ship:
|
|
|
|
|
|
|
|
```console
|
|
|
|
$ ./urbit -F <another-ship> -B <pier>/.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 <ship>
|
|
|
|
```
|
2019-06-17 13:44:08 +03:00
|
|
|
|
2023-01-12 20:23:43 +03:00
|
|
|
[^1]: Unless you specify the pier using the `-c` flag.
|
2019-06-17 13:44:08 +03:00
|
|
|
|
|
|
|
|
2019-08-28 17:32:44 +03:00
|
|
|
[list]: https://groups.google.com/a/urbit.org/forum/#!forum/dev
|
|
|
|
[repo]: https://github.com/urbit/urbit
|
2019-12-18 14:59:22 +03:00
|
|
|
[reba]: https://git-rebase.io/
|
2019-08-28 18:20:09 +03:00
|
|
|
[issu]: https://github.com/urbit/urbit/issues
|
2022-01-05 00:20:29 +03:00
|
|
|
[hoon]: https://urbit.org/docs/hoon/reference/style
|
|
|
|
[main]: https://github.com/urbit/urbit/tree/master/pkg/arvo#maintainers
|