2023-01-09 19:28:47 +03:00
|
|
|
# Contributing
|
2019-06-17 13:44:08 +03:00
|
|
|
|
2023-01-09 19:28:47 +03:00
|
|
|
## Workflow
|
2019-06-17 13:44:08 +03:00
|
|
|
|
2023-01-09 22:02:35 +03:00
|
|
|
Before beginning any unit of work, you should ensure you have a GitHub issue
|
2023-01-09 19:28:47 +03:00
|
|
|
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-09 19:28:47 +03:00
|
|
|
### Branch Names
|
2020-09-01 04:35:52 +03:00
|
|
|
|
2023-01-09 19:28:47 +03:00
|
|
|
Every branch that you intend to put up for review must adhere to the form
|
2023-01-17 23:39:56 +03:00
|
|
|
`i/<N>/<...>`, where `<N>` is the number of the issue that the branch corresponds
|
2023-01-09 19:28:47 +03:00
|
|
|
to and `<...>` is an optional short description of the branch to aid in
|
|
|
|
readability. If `<...>` is omitted, the `/` should be omitted as well, which
|
2023-01-17 23:39:56 +03:00
|
|
|
makes `i/<N>` a well-formed branch name.
|
2022-01-05 00:20:29 +03:00
|
|
|
|
2023-01-09 19:28:47 +03:00
|
|
|
### Commits
|
2019-06-17 13:44:08 +03:00
|
|
|
|
2023-01-09 19:28:47 +03:00
|
|
|
Commit messages should be written in an imperative style and include a mandatory
|
|
|
|
short description and optional long description.
|
2019-06-17 13:44:08 +03:00
|
|
|
|
|
|
|
```
|
2023-01-09 19:28:47 +03:00
|
|
|
Require a short description
|
2019-06-17 13:44:08 +03:00
|
|
|
|
2023-01-09 19:28:47 +03:00
|
|
|
Optionally add a long description.
|
2019-06-17 13:44:08 +03:00
|
|
|
```
|
|
|
|
|
2023-01-09 19:28:47 +03:00
|
|
|
### Pull Requests and Merges
|
2020-09-29 04:58:35 +03:00
|
|
|
|
2023-01-09 22:02:35 +03:00
|
|
|
When your work is ready for review, open a pull request, making sure to link
|
2023-01-09 19:28:47 +03:00
|
|
|
to the tracking issue in the description, which should be formatted as follows
|
2023-01-17 23:39:56 +03:00
|
|
|
(where `<N>` is the number of this work's tracking issue):
|
2020-09-29 04:58:35 +03:00
|
|
|
|
2019-06-17 13:44:08 +03:00
|
|
|
```
|
2023-01-09 19:28:47 +03:00
|
|
|
### Description
|
2019-06-17 13:44:08 +03:00
|
|
|
|
2023-01-17 23:39:56 +03:00
|
|
|
Resolves #<N>.
|
2019-08-28 17:32:44 +03:00
|
|
|
|
2023-01-09 19:28:47 +03:00
|
|
|
Thoroughly describe the changes made.
|
2019-06-17 13:44:08 +03:00
|
|
|
|
2023-01-09 19:28:47 +03:00
|
|
|
### Related
|
2019-06-17 13:44:08 +03:00
|
|
|
|
2023-01-09 19:28:47 +03:00
|
|
|
Reference any related issues, links, papers, etc. here.
|
|
|
|
```
|
2019-06-17 13:44:08 +03:00
|
|
|
|
2023-01-09 19:28:47 +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-03-14 20:15:42 +03:00
|
|
|
With current github permissions, a PR is merge-ready after a single approval
|
|
|
|
from any member of @urbit/runtime. Although anyone can hit the merge button,
|
|
|
|
defer to the PR author to merge unless it's an urgent hotfix that needs to be
|
|
|
|
merged ASAP.
|
|
|
|
|
2023-02-08 19:19:37 +03:00
|
|
|
Once you've collected and addressed feedback and are ready to merge, merge the
|
|
|
|
pull request. Use the default commit message which should default to your PR
|
|
|
|
title and description. Assuming that 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-09 19:28:47 +03:00
|
|
|
## Development Environment
|
2019-06-17 13:44:08 +03:00
|
|
|
|
2023-01-09 19:28:47 +03:00
|
|
|
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
|
2023-01-09 22:02:35 +03:00
|
|
|
address, don't communicate on the live network, and can communicate with other
|
2023-01-09 19:28:47 +03:00
|
|
|
fake ships over the local loopback.
|
2019-06-17 13:44:08 +03:00
|
|
|
|
2023-01-09 19:28:47 +03:00
|
|
|
### Boot a New Fake Ship
|
2019-06-17 13:44:08 +03:00
|
|
|
|
2023-01-09 19:28:47 +03:00
|
|
|
To boot a new fake ship, pass the `-F` flag and a valid Urbit ship name to
|
|
|
|
`urbit`:
|
2019-06-17 13:44:08 +03:00
|
|
|
|
2023-01-09 19:28:47 +03:00
|
|
|
```console
|
|
|
|
$ bazel build :urbit
|
|
|
|
$ ln -s bazel-bin/pkg/vere/urbit urbit
|
|
|
|
$ ./urbit -F <ship>
|
2019-06-17 13:44:08 +03:00
|
|
|
```
|
|
|
|
|
2023-01-09 19:28:47 +03:00
|
|
|
By default, booting a fake ship will use the same pre-compiled kernelspace--
|
2023-01-09 22:02:35 +03:00
|
|
|
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.
|
2019-06-17 13:44:08 +03:00
|
|
|
|
2023-01-09 19:28:47 +03:00
|
|
|
The solid pill (and other pills) live in the [Urbit repo][urbit]. To boot using
|
|
|
|
the solid pill, download the pill and then run:
|
2019-06-17 13:44:08 +03:00
|
|
|
|
2023-01-09 19:28:47 +03:00
|
|
|
```console
|
|
|
|
$ ./urbit -F <ship> -B solid.pill
|
2019-06-17 13:44:08 +03:00
|
|
|
```
|
2019-07-15 13:40:53 +03:00
|
|
|
|
2023-01-09 19:28:47 +03:00
|
|
|
Instead of downloading the pill, you can also generate one yourself using
|
|
|
|
[`dojo`][dojo]:
|
2019-07-15 13:40:53 +03:00
|
|
|
|
2023-01-09 19:28:47 +03:00
|
|
|
```console
|
|
|
|
dojo> .urbit/pill +solid
|
2019-07-15 13:40:53 +03:00
|
|
|
```
|
|
|
|
|
2023-01-09 19:28:47 +03:00
|
|
|
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:
|
2019-08-28 18:20:09 +03:00
|
|
|
|
2023-01-09 19:28:47 +03:00
|
|
|
```console
|
|
|
|
$ ./urbit -F <another-ship> -B <pier>/.urb/put/urbit.pill
|
|
|
|
```
|
2019-08-28 18:20:09 +03:00
|
|
|
|
2023-01-09 19:28:47 +03:00
|
|
|
### Launch an Existing Fake Ship
|
2019-08-28 18:20:09 +03:00
|
|
|
|
2023-01-09 19:28:47 +03:00
|
|
|
To launch an existing fake ship, supply the pier (the ship directory), which is
|
|
|
|
simply the name of the ship[^1], to `urbit`:
|
2019-06-17 13:44:08 +03:00
|
|
|
|
2023-01-09 19:28:47 +03:00
|
|
|
```console
|
|
|
|
$ ./urbit <ship>
|
|
|
|
```
|
2019-06-17 13:44:08 +03:00
|
|
|
|
|
|
|
|
2023-01-09 19:28:47 +03:00
|
|
|
[^1]: Unless you specify the pier using the `-c` flag.
|
2023-02-09 20:29:37 +03:00
|
|
|
|
|
|
|
### Enable Language Server Processing
|
|
|
|
|
|
|
|
We support the [`clangd`](https://clangd.llvm.org/installation)
|
|
|
|
language server, which can be installed directly on your system or
|
|
|
|
via one of the official editor plugins.
|
|
|
|
|
2023-02-10 01:00:49 +03:00
|
|
|
After installing `clangd`, configure it to use the following arguments
|
|
|
|
(location of these arguments may vary depending on your editor plugin or
|
2023-02-10 01:02:39 +03:00
|
|
|
if you've installed `clangd` directly on your system).
|
2023-02-09 20:29:37 +03:00
|
|
|
|
2023-02-10 01:02:22 +03:00
|
|
|
For example, if you use Visual Studio Code, you can add the following to your
|
|
|
|
user settings:
|
|
|
|
|
2023-02-09 20:29:37 +03:00
|
|
|
```json
|
|
|
|
{
|
|
|
|
"clangd.arguments": [
|
|
|
|
"--header-insertion=never",
|
|
|
|
"--compile-commands-dir=${workspaceFolder}/",
|
|
|
|
"--query-driver=**",
|
|
|
|
],
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2023-02-10 01:05:10 +03:00
|
|
|
For other editors, please refer to the
|
|
|
|
[editor plugin documentation](https://clangd.llvm.org/installation.html#editor-plugins).
|
|
|
|
|
2023-02-09 20:29:37 +03:00
|
|
|
Finally, run the following command to generate a `compile_commands.json` file,
|
|
|
|
which is used by `clangd` to enable all of its features (e.g. code completion,
|
|
|
|
jump to definition, cross-references, hovering, symbol renaming, etc.):
|
|
|
|
|
|
|
|
```console
|
|
|
|
bazel run //bazel:refresh_compile_commands
|
2023-03-14 20:15:42 +03:00
|
|
|
```
|