CONTRIBUTING.md 7.39 KB
 Nick Mathewson committed Jun 17, 2021 1 # Contributing to Arti  George Kadianakis committed Feb 08, 2021 2   Nick Mathewson committed Jun 17, 2021 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).  George Kadianakis committed Feb 08, 2021 8   Nick Mathewson committed Jun 17, 2021 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.  Nick Mathewson committed Aug 09, 2021 19 ## Setting up your Development Environment  S0AndS0 committed Aug 06, 2021 20 21 22 23 24 25  The following section is **not** an exhaustive guide, and only covers common setup and development tasks. **Install dependencies**  Nick Mathewson committed Aug 09, 2021 26 You'll need to have a working Rust environment to build the code, and a  Lennart Kloock committed Mar 05, 2022 27 28 working Git installation to fetch the code. Additionally, please install the SQLite 3 development files and shellcheck to successfully run git hooks.  Nick Mathewson committed Aug 09, 2021 29   S0AndS0 committed Aug 06, 2021 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 committed Oct 25, 2021 34 - [Git](https://git-scm.com/downloads) note, for Linux, macOS, and some  S0AndS0 committed Aug 06, 2021 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.  S0AndS0 committed Aug 06, 2021 40   41 42 - SQLite 3 development files (e.g. available via apt install libsqlite3-dev)  Lennart Kloock committed Mar 05, 2022 43 44 - For git hooks: [shellcheck](https://github.com/koalaman/shellcheck#installing) (used in [maint/shellcheck_all](./maint/shellcheck_all))  S0AndS0 committed Aug 06, 2021 45   Nick Mathewson committed Aug 09, 2021 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  S0AndS0 committed Aug 06, 2021 51   Nick Mathewson committed Aug 09, 2021 52 This will create a new git checkout in a directory called arti.  S0AndS0 committed Aug 06, 2021 53   Nick Mathewson committed Aug 09, 2021 54 55 56 **Update the source code** To get the latest updates, you can run:  S0AndS0 committed Aug 06, 2021 57 58 59 $ git pull origin main  Nick Mathewson committed Aug 09, 2021 60 > Note, if you're working on a local git branch it may be wise to use fetch  S0AndS0 committed Aug 06, 2021 61 62 63 64 > and merge options instead > > $git fetch origin >$ git merge origin/main  Nick Mathewson committed Aug 09, 2021 65 66 > > Please see a good Git tutorial for more information  S0AndS0 committed Aug 06, 2021 67   Nick Mathewson committed Aug 09, 2021 68 **Running the unit tests**  S0AndS0 committed Aug 06, 2021 69   Nick Mathewson committed Aug 09, 2021 70  $cargo test --all-features  S0AndS0 committed Aug 06, 2021 71   eta committed May 10, 2022 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/  S0AndS0 committed Aug 06, 2021 79 80 81  **Add fork URL**  Nick Mathewson committed Aug 09, 2021 82 83 84 If you've created an account at gitlab.torproject.org, you can add a link to your forked arti repository at:  S0AndS0 committed Aug 06, 2021 85 86 87  $git remote add _name_ git@gitlab.torproject.org:_name_/arti.git$ git fetch _name_  Nick Mathewson committed Jan 21, 2022 88 > *Tip*: replace _name_ in above, and following, commands to reflect your sign  S0AndS0 committed Aug 06, 2021 89 90 > in name. >  Nick Mathewson committed Jan 21, 2022 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  S0AndS0 committed Aug 06, 2021 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  Nick Mathewson committed Jun 17, 2021 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.  George Kadianakis committed Feb 08, 2021 115 116  To do so, we will launch arti independently from Tor Browser. Build arti with  Nick Mathewson committed Jun 17, 2021 117 118 cargo build --release. After that launch it with some basic configuration parameters:  George Kadianakis committed Feb 08, 2021 119   eta committed Oct 27, 2021 120 $ ./target/release/arti proxy -l debug -p 9150  George Kadianakis committed Feb 08, 2021 121 122  This will ensure that arti sets its SOCKS port on 9150. Now we need to launch  Nick Mathewson committed Jul 23, 2021 123 124 Tor Browser and instruct it to use that SOCKS port.  Steven Murdoch committed Mar 04, 2022 125 ### Linux  George Kadianakis committed Feb 08, 2021 126 127 128  $TOR_SKIP_LAUNCH=1 TOR_SOCKS_PORT=9150 ./start-tor-browser.desktop  Steven Murdoch committed Mar 04, 2022 129 ### OS X  Nick Mathewson committed Jul 23, 2021 130 131 132 $ TOR_SKIP_LAUNCH=1 TOR_SOCKS_PORT=9150 /path/to/Tor\ Browser/Contents/MacOS/firefox  Steven Murdoch committed Mar 04, 2022 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"  Nick Mathewson committed Jul 23, 2021 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.  Nick Mathewson committed Jun 17, 2021 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.  George Kadianakis committed Feb 08, 2021 153 154  Enjoy hacking on arti!  Nick Mathewson committed Jun 17, 2021 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 committed May 26, 2022 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.  Nick Mathewson committed Jun 17, 2021 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  Nick Mathewson committed Dec 20, 2021 174 like "FIXME" or "TODO".  Nick Mathewson committed Jun 17, 2021 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.  Ian Jackson committed Jan 20, 2022 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.)