CONTRIBUTING.md 7.39 KB
Newer Older
1
# Contributing to Arti
2

3
4
5
6
7
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).
8

9
10
11
12
13
14
15
16
17
18
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.

19
## Setting up your Development Environment
20
21
22
23
24
25

The following section is **not** an exhaustive guide, and only covers common
setup and development tasks.

**Install dependencies**

26
You'll need to have a working Rust environment to build the code, and a
Lennart Kloock's avatar
Lennart Kloock committed
27
28
working Git installation to fetch the code. Additionally, please install
the SQLite 3 development files and shellcheck to successfully run git hooks.
29

30
31
32
33
- [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)

Dimitris Apostolou's avatar
Dimitris Apostolou committed
34
- [Git](https://git-scm.com/downloads) note, for Linux, macOS, and some
35
  Unix-like devices Git may be available via a package manager; `apt`, `brew`,
36
37
38
39
  `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`.
40

41
42
- SQLite 3 development files (e.g. available via `apt install libsqlite3-dev`)
  
Lennart Kloock's avatar
Lennart Kloock committed
43
44
- For git hooks: [shellcheck](https://github.com/koalaman/shellcheck#installing)
  (used in [`maint/shellcheck_all`](./maint/shellcheck_all))
45

46
47
48
49
50
**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
51

52
This will create a new git checkout in a directory called `arti`.
53

54
55
56
**Update the source code**

To get the latest updates, you can run:
57
58
59

    $ git pull origin main

60
> Note, if you're working on a local git branch it may be wise to use `fetch`
61
62
63
64
> and `merge` options instead
>
>     $ git fetch origin
>     $ git merge origin/main
65
66
>
> Please see a good Git tutorial for more information
67

68
**Running the unit tests**
69

70
    $ cargo test --all-features
71

72
73
74
75
76
77
78
**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/
79
80
81

**Add fork URL**

82
83
84
If you've created an account at `gitlab.torproject.org`, you can add a
link to your forked arti repository at:

85
86
87
    $ git remote add _name_ git@gitlab.torproject.org:_name_/arti.git
    $ git fetch _name_

88
> *Tip*: replace `_name_` in above, and following, commands to reflect your sign
89
90
> in name.
>
91
92
93
94
95
96
97
> *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
98
99
100
101
102
103
104
105
106
107
108
109
> [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

110
111
112
113
114
## Using Arti with Torbrowser

A good first step to start hacking on arti might be to hook it up with your
Tor Browser. Please note that arti is still a work in progress and hence you
should assume that it **provides no security** at the moment.
115
116

To do so, we will launch arti independently from Tor Browser. Build arti with
117
118
`cargo build --release`.  After that launch it with some basic
configuration parameters:
119

eta's avatar
eta committed
120
    $ ./target/release/arti proxy -l debug -p 9150
121
122

This will ensure that arti sets its SOCKS port on 9150. Now we need to launch
123
124
Tor Browser and instruct it to use that SOCKS port.

125
### Linux
126
127
128

    $ TOR_SKIP_LAUNCH=1 TOR_SOCKS_PORT=9150 ./start-tor-browser.desktop

129
### OS X
130
131
132

    $ TOR_SKIP_LAUNCH=1 TOR_SOCKS_PORT=9150 /path/to/Tor\ Browser/Contents/MacOS/firefox

133
134
135
136
137
138
139
140
141
142
### Windows

Create a shortcut with the `Target` set to:

    C:\Windows\System32\cmd.exe /c "SET TOR_SKIP_LAUNCH=1&& SET TOR_SOCKS_PORT=9150&& START /D ^"C:\path\to\Tor Browser\Browser^" firefox.exe"
    
and `Start in` set to:

    "C:\path\to\Tor Browser\Browser"

143
144
145
146
147
148
149
(You may need to adjust the actual path to wherever you have put your Tor
Browser.)

When you start Tor browser, it will give you a big red error page because
Arti isn't offering it a control port interface.  But it will still work!
Try [check.torproject.org](https://check.torproject.org/) to be sure.

150
151
152
The resulting Tor Browser should be using arti.  Note that onion services
won't work (Arti doesn't have them yet), and neither will any feature
depending on Tor's control-port protocol.
153
154

Enjoy hacking on arti!
155
156
157
158
159
160
161

## 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).

trinity-1686a's avatar
trinity-1686a committed
162
163
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.
164
165
166
167
168
169
170
171
172
173

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
174
like "FIXME" or "TODO".
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203

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.

204
205
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`.)