mirror of
https://github.com/ilyakooo0/urbit.git
synced 2024-09-11 10:46:43 +03:00
252 lines
9.7 KiB
Markdown
252 lines
9.7 KiB
Markdown
## Workflow
|
|
|
|
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.
|
|
|
|
## Issues
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
### Feature Branch Names
|
|
|
|
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`.
|
|
|
|
### Commits
|
|
|
|
Commits should generally be relevant, atomic, and have descriptions formatted in
|
|
the following manner:
|
|
|
|
> component: short description
|
|
>
|
|
> long description
|
|
|
|
The 'component' is a short prefix of what area of the codebase the commit
|
|
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.
|
|
|
|
Every individual commit should at a minimum be in a compiling and runnable state.
|
|
Broken commits or commits simply marked "wip" are not allowed. If you need to
|
|
clean up the commits in your branch, you can soft reset to an earlier state and
|
|
recommit with better metadata (or if the change is small enough, squash to one
|
|
good commit at the end).
|
|
|
|
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.
|
|
|
|
Here is an example of our commit format, taken from a commit in the history:
|
|
|
|
> zuse: remove superfluous 'scup' and 'culm' types.
|
|
>
|
|
> %zuse includes definitions for 'scup' and 'culm', both of which are
|
|
> 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).
|
|
>
|
|
> This commit deletes 'scup' and 'culm' and refactors what little code made use
|
|
> of them.
|
|
|
|
Note that the short description is prefixed by `zuse:`, which is what the commit
|
|
touches. Otherwise it just includes a summary of the change.
|
|
|
|
Here's another example:
|
|
|
|
> build: give arvo a high priority
|
|
>
|
|
> 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.
|
|
>
|
|
> Fixes #1912.
|
|
|
|
Note that it cites a previous relevant commit, `0bdced981e4`, in its summary,
|
|
and also points at the issue that it resolves.
|
|
|
|
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`.
|
|
|
|
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.
|
|
|
|
### Pull Requests and Merges
|
|
|
|
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):
|
|
|
|
```
|
|
### Description
|
|
|
|
Resolves #<N>.
|
|
|
|
Thoroughly describe the changes made.
|
|
|
|
### Related
|
|
|
|
Reference any related issues, links, papers, etc. here.
|
|
```
|
|
|
|
Tests will run automatically via GitHub Actions when you open a pull request or
|
|
push new commits to an existing pull request.
|
|
|
|
Once you've collected and addressed feedback, tests are passing, and your PR has
|
|
been approved, merge the pull request.
|
|
|
|
**Note**: If you are merging into develop, you *must* be syncing OTAs from
|
|
`~binnec-dozzod-marzod` which gets the tip of develop deployed to it. If
|
|
your merge breaks `binnec` it's your responsibility to alert people and
|
|
fix it. Your PR is shipped when it's successfully been deployed to
|
|
`~binnec` and picked up by your personal ship. If you're merging on behalf
|
|
of an external developer, this is also your responsibility.
|
|
|
|
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.
|
|
|
|
## 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.
|
|
|
|
### Kernel Development and Pills
|
|
|
|
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.
|
|
|
|
You can find the latest solid pill, as well as the latest so-called *brass*
|
|
and *ivory* pills, in the `bin/` directory at the repository root.
|
|
|
|
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].
|
|
|
|
```
|
|
$ git lfs init
|
|
$ git lfs pull
|
|
```
|
|
|
|
[git-lfs]: https://git-lfs.github.com
|
|
|
|
The +solid command is used to write the compiled kernel to a file.
|
|
|
|
```
|
|
> .urbit/pill +solid
|
|
```
|
|
|
|
When the compilation finishes, your pill will be found in the `[pier]/.urb/put/`
|
|
directory as `urbit.pill`.
|
|
|
|
You can boot a new ship from your local pill with `-B`:
|
|
|
|
```
|
|
$ urbit -F zod -B path/to/urbit.pill my-fake-zod
|
|
```
|
|
|
|
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`.
|
|
|
|
Whenever you make a contribution to the kernel, please create a new solid pill
|
|
via:
|
|
|
|
```
|
|
sh/update-solid-pill
|
|
```
|
|
|
|
You should include the updated pill in the same commit that updates the source.
|
|
|
|
## 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 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 "solid" pill reduces this time to a couple minutes.
|
|
|
|
To boot using the solid pill, download or create one as described in the Kernel
|
|
Development and Pills section above and then run the following:
|
|
|
|
```console
|
|
$ ./urbit -F <ship> -B solid.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>
|
|
```
|
|
|
|
[^1]: Unless you specified the pier name using the `-c` flag.
|
|
|
|
|
|
[list]: https://groups.google.com/a/urbit.org/forum/#!forum/dev
|
|
[repo]: https://github.com/urbit/urbit
|
|
[reba]: https://git-rebase.io/
|
|
[issu]: https://github.com/urbit/urbit/issues
|
|
[hoon]: https://urbit.org/docs/hoon/reference/style
|
|
[main]: https://github.com/urbit/urbit/tree/master/pkg/arvo#maintainers
|