1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
|
---
title: Overview
---
# How to contribute
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://community.torproject.org/policies/code_of_conduct/).
The new-account process on our gitlab instance is moderated, to reduce spam and abuse. Request an account to gain access to contribute.
## 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.
## Getting started
You might want to begin by looking around the [codebase](https://gitlab.torproject.org/tpo/core/arti/), or getting to know our [architecture](/contributing/for-developers/architecture).
### Finding something to work on
- 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.
- 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.
We make notes throughout the document in comments with strings like "FIXME" or "TODO".
Sometimes these can sound deceptively simple; keep in mind that usually there's a reason
that someone wrote the comment instead of just doing the task.
See "Before you start coding", below.
When we have TODOs that we want to fix prior to the release of a particular feature or milestone, we define a special TODO format. Right now, we have "TODO HS" (or "TODO hs") for things we intend to fix before we release support for Tor Hidden Services (.onion services).
If you want to make a temporary change that should not to be merged, mark it with <code>XXXX</code>. This will be spotted by the CI, preventing a mistaken merge.
We have provided a list of features that we wish other crates had in a file called [`WANT_FROM_OTHER_CRATES`](https://gitlab.torproject.org/tpo/core/arti/-/blob/main/WANT_FROM_OTHER_CRATES), so that you can find a place to contribute even if you don't want to write new code.
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%5B%5D=First%20Contribution). That label means that we think they might be a good place to start out.
### Before you start coding
For all but the most trivial of changes, it's best to get in touch with the
development team before beginning work, to ensure that there's agreement about
what you plan to do and how, and to avoid having multiple people try to work on
the same thing at once.
If there's already an issue filed for the work, you can comment on the issue to
verify whether this is a good issue to work on, and to get a go-ahead for your design
and development plan. Often a sentence or two is sufficient, at least to start
the conversation:
"I'll rename X to Y"; "I'll prevent this function from retrying a download
indefinitely by adding a limit of X retries, overridable by a config file option
Y".
If there's not already an issue filed, you can file an issue yourself, though
before doing that you may want to touch base with the developers on the
[#tor-dev IRC channel](https://www.torproject.org/contact/) to double-check that
one doesn't already exist.
## Setting up your Development Environment
The following section is **not** an exhaustive guide, and only covers common setup and development tasks.
### Install build dependencies
You'll need to have a working Rust environment to build the code, and a working Git installation to fetch the code. Additionally, please install the SQLite 3 development files and shellcheck to successfully run git hooks.
- [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)
- [Git](https://git-scm.com/downloads) note, for Linux, macOS, and some Unix-like devices Git may be available via a package manager; `apt`, `brew`, `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`.
- SQLite 3 development files (e.g. available via `apt install libsqlite3-dev`)
- For git hooks: [shellcheck](https://github.com/koalaman/shellcheck#installing) used in [`maint/shellcheck_all`](https://gitlab.torproject.org/tpo/core/arti/-/blob/main/maint/shellcheck_all)
### (Optional) install development dependencies
TL;DR: [`./maint/check_env`](https://gitlab.torproject.org/tpo/core/arti/-/blob/main/maint/check_env)
If you plan to run scripts inside the [`maint/`](https://gitlab.torproject.org/tpo/core/arti/-/tree/main/maint) directory, that are scripts such as coverage reports, you'll need a few more dependencies. For this, please execute `./maint/check_env`, which will check your host machine if all required dependencies are satisfied. If this is not the case, it will report the missing ones. Keep in mind that this list is pretty comprehensive and not every script requires all of these dependencies.
### 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
```
This will create a new git checkout in a directory called `arti`.
### Update the source code
To get the latest updates, you can run:
```
$ git pull origin main
```
> Note, if you're working on a local git branch it may be wise to use fetch and merge options instead
>
>
> ```
> $ git fetch origin
> $ git merge origin/main
> ```
>
> Please see a good Git tutorial for more information
>
### Running the unit tests
You can run the unit tests with the command:
```
$ cargo test --all-features
```
### 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/
```
### Add fork URL
If you've created an account at `gitlab.torproject.org`, you can add a
link to your forked arti repository at:
```
$ git remote add _name_ [email protected]:_name_/arti.git
$ git fetch _name_
```
> Tip: replace _name_ in above, and following, commands to reflect your sign in name.
>
>
> *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 [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`
>
Please do not to rebase and squash MRs during the review cycle. If you want to make changes to your MR, please add new commits rather than squashing. You can use the [`fixup!`](https://git-scm.com/docs/git-rebase#Documentation/git-rebase.txt---autosquash) or `squash!` ([autosquash](https://thoughtbot.com/blog/autosquashing-git-commits)) syntax. This is a good idea if the un-fixed state breaks the tests or is otherwise broken, but is not needed otherwise.
## What to watch out for
There are some instances where we deviating from the existing Tor protocol under the assumption that certain proposals will be accepted. See our [protocol support and compatibility guide](/guides/compatibility) for more information. This code does not attempt to be indistinguishable from the current Tor implementation.
When building the docs with `cargo doc`, use `--workspace --all-features`, or you may find broken links. We welcome fixes to links broken with `--all-features`.
You can also use the following command to reveal (unstable) internal information:
```sh
cargo doc --workspace --all-features --document-private-items
```
Enjoy hacking on Arti!
|
