2021-06-17 17:18:28 +01:00
|
|
|
# Contributing to Arti
|
2021-02-08 18:39:52 +00:00
|
|
|
|
2021-06-17 17:18:28 +01:00
|
|
|
We welcome new contributors! You can get in contact with us on
|
|
|
|
[our gitlab instance](https://gitlab.torproject.org/), or on the
|
|
|
|
[`\#tor-dev IRC` channel on OFTC](https://www.torproject.org/contact/).
|
|
|
|
Make sure to familiarize yourself with our
|
|
|
|
[Code of Conduct](https://gitweb.torproject.org/community/policies.git/plain/code_of_conduct.txt).
|
2021-02-08 18:39:52 +00:00
|
|
|
|
2021-06-17 17:18:28 +01:00
|
|
|
The new-account process on our gitlab instance is moderated, to reduce
|
|
|
|
spam and abuse. (*Insert instructions for anonymous usage here*)
|
|
|
|
|
|
|
|
## Licensing notice
|
|
|
|
|
|
|
|
Unless you explicitly state otherwise, any contribution intentionally
|
|
|
|
submitted for inclusion in the work by you, as defined in the Apache-2.0
|
|
|
|
license, shall be dual licensed as above, without any additional terms or
|
|
|
|
conditions.
|
|
|
|
|
2021-08-09 17:42:10 +01:00
|
|
|
## Setting up your Development Environment
|
2021-08-06 23:31:45 +01:00
|
|
|
|
|
|
|
The following section is **not** an exhaustive guide, and only covers common
|
|
|
|
setup and development tasks.
|
|
|
|
|
|
|
|
**Install dependencies**
|
|
|
|
|
2021-08-09 17:42:10 +01:00
|
|
|
You'll need to have a working Rust environment to build the code, and a
|
2022-03-05 11:23:46 +00:00
|
|
|
working Git installation to fetch the code. Additionally, please install
|
|
|
|
the SQLite 3 development files and shellcheck to successfully run git hooks.
|
2021-08-09 17:42:10 +01:00
|
|
|
|
2021-08-06 23:31:45 +01:00
|
|
|
- [Rust](https://www.rust-lang.org/tools/install) note, for Windows devices
|
|
|
|
check the
|
|
|
|
[Other Installation Methods](https://forge.rust-lang.org/infra/other-installation-methods.html)
|
|
|
|
|
2021-10-25 17:58:42 +01:00
|
|
|
- [Git](https://git-scm.com/downloads) note, for Linux, macOS, and some
|
2021-08-06 23:31:45 +01:00
|
|
|
Unix-like devices Git may be available via a package manager; `apt`, `brew`,
|
2022-03-08 13:27:31 +00:00
|
|
|
`yum`, `pacman`, etc. Git needs to be compiled with PCRE support to allow
|
|
|
|
the use of `git grep -P` in the git hooks. PCRE support is the default in
|
|
|
|
some packages, but if you compile from source set `USE_LIBPCRE=YesPlease`
|
|
|
|
when running `make` or `--with-libpcre` when running `./configure`.
|
2021-08-06 23:31:45 +01:00
|
|
|
|
2022-03-05 11:06:37 +00:00
|
|
|
- SQLite 3 development files (e.g. available via `apt install libsqlite3-dev`)
|
|
|
|
|
2022-03-05 11:23:46 +00:00
|
|
|
- For git hooks: [shellcheck](https://github.com/koalaman/shellcheck#installing)
|
|
|
|
(used in [`maint/shellcheck_all`](./maint/shellcheck_all))
|
2021-08-06 23:31:45 +01:00
|
|
|
|
2021-08-09 17:42:10 +01:00
|
|
|
**Clone the source code**
|
|
|
|
|
|
|
|
In order to get a copy of the latest version of the arti source code:
|
|
|
|
|
|
|
|
$ git clone https://gitlab.torproject.org/tpo/core/arti.git
|
2021-08-06 23:31:45 +01:00
|
|
|
|
2021-08-09 17:42:10 +01:00
|
|
|
This will create a new git checkout in a directory called `arti`.
|
2021-08-06 23:31:45 +01:00
|
|
|
|
2021-08-09 17:42:10 +01:00
|
|
|
**Update the source code**
|
|
|
|
|
|
|
|
To get the latest updates, you can run:
|
2021-08-06 23:31:45 +01:00
|
|
|
|
|
|
|
$ git pull origin main
|
|
|
|
|
2021-08-09 17:42:10 +01:00
|
|
|
> Note, if you're working on a local git branch it may be wise to use `fetch`
|
2021-08-06 23:31:45 +01:00
|
|
|
> and `merge` options instead
|
|
|
|
>
|
|
|
|
> $ git fetch origin
|
|
|
|
> $ git merge origin/main
|
2021-08-09 17:42:10 +01:00
|
|
|
>
|
|
|
|
> Please see a good Git tutorial for more information
|
2021-08-06 23:31:45 +01:00
|
|
|
|
2021-08-09 17:42:10 +01:00
|
|
|
**Running the unit tests**
|
2021-08-06 23:31:45 +01:00
|
|
|
|
2021-08-09 17:42:10 +01:00
|
|
|
$ cargo test --all-features
|
2021-08-06 23:31:45 +01:00
|
|
|
|
2022-05-10 13:36:49 +01:00
|
|
|
**Installing git hooks**
|
|
|
|
|
|
|
|
This repository contains some useful [git hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks)
|
|
|
|
that you might want to use to help avoid your code failing CI checks.
|
|
|
|
You can install them with
|
|
|
|
|
|
|
|
$ cp -v maint/hooks/* .git/hooks/
|
2021-08-06 23:31:45 +01:00
|
|
|
|
|
|
|
**Add fork URL**
|
|
|
|
|
2021-08-09 17:42:10 +01:00
|
|
|
If you've created an account at `gitlab.torproject.org`, you can add a
|
|
|
|
link to your forked arti repository at:
|
|
|
|
|
2021-08-06 23:31:45 +01:00
|
|
|
$ git remote add _name_ git@gitlab.torproject.org:_name_/arti.git
|
|
|
|
$ git fetch _name_
|
|
|
|
|
2022-01-21 15:51:59 +00:00
|
|
|
> *Tip*: replace `_name_` in above, and following, commands to reflect your sign
|
2021-08-06 23:31:45 +01:00
|
|
|
> in name.
|
|
|
|
>
|
2022-01-21 15:51:59 +00:00
|
|
|
> *Note*: to fork this repository, or contribute to Issues and Merge Requests,
|
|
|
|
> you will need an account on our gitlab server. If you don't have an
|
|
|
|
> account there, you can either
|
|
|
|
> [request an account](https://gitlab.onionize.space/) or
|
|
|
|
> [report a bug anonymously](https://anonticket.onionize.space/).
|
|
|
|
>
|
|
|
|
> Check the
|
2021-08-06 23:31:45 +01:00
|
|
|
> [Sign In](https://gitlab.torproject.org/users/sign_in?redirect_to_referer=yes)
|
|
|
|
> page for further instructions on requesting access.
|
|
|
|
|
|
|
|
**Push to fork**
|
|
|
|
|
|
|
|
$ git push _name_ main
|
|
|
|
|
|
|
|
> Tip, to open a Merge Request navigate to the Merge Request tab for your
|
|
|
|
> account's fork; URL will be similar to the following
|
|
|
|
>
|
|
|
|
> https://gitlab.torproject.org/_name_/arti/-/merge_requests
|
|
|
|
|
2021-06-17 17:18:28 +01:00
|
|
|
## Where are some good places to start hacking?
|
|
|
|
|
|
|
|
You might want to begin by looking around the
|
|
|
|
[codebase](https://gitlab.torproject.org/tpo/core/arti/), or getting to
|
|
|
|
know our [architecture](./doc/Architecture.md).
|
|
|
|
|
2022-05-26 12:14:00 +01:00
|
|
|
More tests would always be great. You can look at the [coverage reports](https://tpo.pages.torproject.net/core/arti/coverage/)
|
|
|
|
to find out what parts need the more love.
|
2021-06-17 17:18:28 +01:00
|
|
|
|
|
|
|
Parsing more Tor document types would be neat.
|
|
|
|
|
|
|
|
More documentation examples would be great.
|
|
|
|
|
|
|
|
Improvements or bugfixes to the existing code would be great.
|
|
|
|
|
|
|
|
Improving the look and feel of the documentation would also rock.
|
|
|
|
|
|
|
|
I've made a bunch of notes throughout the document in comments with strings
|
2021-12-20 16:31:20 +00:00
|
|
|
like "FIXME" or "TODO".
|
2021-06-17 17:18:28 +01:00
|
|
|
|
|
|
|
There is a list of features that I wish other crates had in a file called
|
|
|
|
`WANT_FROM_OTHER_CRATES`.
|
|
|
|
|
|
|
|
Finally, check out
|
|
|
|
[the bugtracker](https://gitlab.torproject.org/tpo/core/arti/-/issues).
|
|
|
|
There are some tickets there labeled as
|
|
|
|
["First Contribution"](https://gitlab.torproject.org/tpo/core/arti/-/issues?scope=all&utf8=%E2%9C%93&state=opened&label_name[]=First%20Contribution):
|
|
|
|
that label means that we think they might be a good place to start out.
|
|
|
|
|
|
|
|
## Caveat haxxor: what to watch out for
|
|
|
|
|
|
|
|
Please don't assume that what you see here is good Rust: we've tried to
|
|
|
|
follow best practices, but we've been learning Rust here as we go along.
|
|
|
|
There are probably aspects of the language or its ecosystem that we're
|
|
|
|
getting wrong.
|
|
|
|
|
|
|
|
Almost nothing about this code should be taken as "final" -- I expect
|
|
|
|
that we'll need to refactor and move around a whole bunch of code, add a
|
|
|
|
bunch of APIs, split crates, merge crates, and so on.
|
|
|
|
|
|
|
|
There are some places where I am deviating from the existing Tor
|
|
|
|
protocol under the assumption that certain proposals will be
|
|
|
|
accepted. See [Compatibility.md](./doc/Compatibility.md) for more
|
|
|
|
information.
|
|
|
|
|
|
|
|
This code does not attempt to be indistinguishable from the current Tor
|
|
|
|
implementation.
|
|
|
|
|
2022-01-20 17:36:37 +00:00
|
|
|
When building the docs with `cargo doc`, use `--all-features`, or you may
|
|
|
|
find broken links. (We welcome fixes to links broken with `--all-features`.)
|
2022-09-02 16:49:57 +01:00
|
|
|
|
|
|
|
Enjoy hacking on arti!
|