claude is gud

1 files changed, 173 insertions, 0 deletions

diff --git a/vere/CONTRIBUTING.md b/vere/CONTRIBUTING.md
new file mode 100644
index 0000000..e2738b8
--- /dev/null
+++ b/vere/CONTRIBUTING.md
@@ -0,0 +1,173 @@
+# Contributing
+
+## Workflow
+
+Before beginning any unit of work, you should ensure you 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.
+
+### 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.
+
+### Commits
+
+Commit messages should be written in an imperative style and include a mandatory
+short description and optional long description.
+
+```
+Require a short description
+
+Optionally add a long description.
+```
+
+### 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.
+
+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.
+
+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.
+
+
+## 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>
+```
+
+
+[^1]: Unless you specify the pier using the `-c` flag.
+
+### 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.
+
+After installing `clangd`, configure it to use the following arguments 
+(location of these arguments may vary depending on your editor plugin or 
+if you've installed `clangd` directly on your system).
+
+For example, if you use Visual Studio Code, you can add the following to your
+user settings:
+
+```json
+{
+  "clangd.arguments": [
+    "--header-insertion=never",
+    "--compile-commands-dir=${workspaceFolder}/",
+    "--query-driver=**",
+  ],
+}
+```
+
+For other editors, please refer to the 
+[editor plugin documentation](https://clangd.llvm.org/installation.html#editor-plugins).
+
+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
+```
+
+### Debugging
+
+Prefer GDB for interactive debugging.  You need to compile with the symbol table:
+
+```bash
+bazel build :urbit --compilation_mode=dbg
+gdb --args ./bazel-bin/pkg/vere/urbit zod
+```
+
+In GDB, set the following, and any breakpoints (e.g. `break u3m_bail`):
+
+```gdb
+set follow-fork-mode child
+handle SIGSEGV nostop noprint
+```
+
+Then run the Urbit program as usual with `r`.