| blob | 271e2d751770b8541a9abdf292c2058a703213bd |
1 # Getting started in Tor development
3 Congratulations! You've found this file, and you're reading it! This
4 means that you might be interested in getting started in developing Tor.
6 (_This guide is just about Tor itself--the small network program at the
7 heart of the Tor network--and not about all the other programs in the
8 whole Tor ecosystem._)
10 If you are looking for a more bare-bones, less user-friendly information
11 dump of important information, you might like reading the
12 [doxygen output](https://src-ref.docs.torproject.org/tor/index.html).
13 You probably should skim some of the topic headings there before you write
14 your first patch.
16 ## Required background
18 First, I'm going to assume that you can build Tor from source, and that
19 you know enough of the C language to read and write it. (See the README
20 file that comes with the Tor source for more information on building it,
21 and any high-quality guide to C for information on programming.)
23 I'm also going to assume that you know a little bit about how to use
24 Git, or that you're able to follow one of the several excellent guides
25 at [git-scm](https://git-scm.org) to learn.
27 Most Tor developers develop using some Unix-based system, such as GNU/Linux,
28 BSD, or macOS. It's okay to develop on Windows if you want, but you're
29 going to have a more difficult time.
31 ## Getting your first patch into Tor
33 Once you've reached this point, here's what you need to know.
35 1. Get the source.
37 We keep our source under version control in Git. To get the latest
38 version, run:
40 ```console
41 $ git clone https://git.torproject.org/git/tor
42 ```
44 This will give you a checkout of the main branch. If you're
45 going to fix a bug that appears in a stable version, check out the
46 appropriate "maint" branch, as in:
48 ```console
49 $ git checkout maint-0.4.3
50 ```
52 2. Find your way around the source.
54 Our overall code structure is explained in our
55 [source documentation](https://src-ref.docs.torproject.org/tor/index.html).
57 Find a part of the code that looks interesting to you, and start
58 looking around it to see how it fits together!
60 We do some unusual things in our codebase. Our testing-related
61 practices and kludges are explained in `doc/HACKING/WritingTests.md`.
63 If you see something that doesn't make sense, we love to get
64 questions!
66 3. Find something cool to hack on.
68 You may already have a good idea of what you'd like to work on, or
69 you might be looking for a way to contribute.
71 Many people have gotten started by looking for an area where they
72 personally felt Tor was underperforming, and investigating ways to
73 fix it. If you're looking for ideas, you can head to
74 [gitlab](https://gitlab.torproject.org) our bug tracking tool and look for
75 tickets that have received the "First Contribution" label: these are ones
76 that developers
77 think would be pretty simple for a new person to work on. For a bigger
78 challenge, you might want to look for tickets with the "Project Ideas"
79 keyword: these are tickets that the developers think might be a
80 good idea to build, but which we have no time to work on any time
81 soon.
83 Or you might find another open ticket that piques your
84 interest. It's all fine!
86 For your first patch, it is probably NOT a good idea to make
87 something huge or invasive. In particular, you should probably
88 avoid:
90 * Major changes spread across many parts of the codebase.
91 * Major changes to programming practice or coding style.
92 * Huge new features or protocol changes.
94 4. Meet the developers!
96 We discuss stuff on the tor-dev mailing list and on the `#tor-dev`
97 IRC channel on OFTC. We're generally friendly and approachable,
98 and we like to talk about how Tor fits together. If we have ideas
99 about how something should be implemented, we'll be happy to share
100 them.
102 We currently have a patch workshop at least once a week, where
103 people share patches they've made and discuss how to make them
104 better. The time might change in the future, but generally,
105 there's no bad time to talk, and ask us about patch ideas.
107 5. Do you need to write a design proposal?
109 If your idea is very large, or it will require a change to Tor's
110 protocols, there needs to be a written design proposal before it
111 can be merged. (We use this process to manage changes in the
112 protocols.) To write one, see the instructions at
113 [the Tor proposal process](https://gitweb.torproject.org/torspec.git/plain/proposals/001-process.txt).
114 If you'd like help writing a proposal, just ask! We're happy to
115 help out with good ideas.
117 You might also like to look around the rest of that directory, to
118 see more about open and past proposed changes to Tor's behavior.
120 6. Writing your patch
122 As you write your code, you'll probably want it to fit in with the
123 standards of the rest of the Tor codebase so it will be easy for us
124 to review and merge. You can learn our coding standards in
125 `doc/HACKING` directory.
127 If your patch is large and/or is divided into multiple logical
128 components, remember to divide it into a series of Git commits. A
129 series of small changes is much easier to review than one big lump.
131 7. Testing your patch
133 We prefer that all new or modified code have unit tests for it to
134 ensure that it runs correctly. Also, all code should actually be
135 _run_ by somebody, to make sure it works.
137 See `doc/HACKING/WritingTests.md` for more information on how we test things
138 in Tor. If you'd like any help writing tests, just ask! We're
139 glad to help out.
141 8. Submitting your patch
143 We review patches through tickets on our bugtracker at
144 [gitlab](https://gitlab.torproject.org). You can either upload your patches there, or
145 put them at a public git repository somewhere we can fetch them
146 (like gitlab, github or bitbucket) and then paste a link on the appropriate
147 ticket.
149 Once your patches are available, write a short explanation of what
150 you've done on trac, and then change the status of the ticket to
151 needs_review.
153 9. Review, Revision, and Merge
155 With any luck, somebody will review your patch soon! If not, you
156 can ask on the IRC channel; sometimes we get really busy and take
157 longer than we should. But don't let us slow you down: you're the
158 one who's offering help here, and we should respect your time and
159 contributions.
161 When your patch is reviewed, one of these things will happen:
163 * The reviewer will say "_looks good to me_" and your
164 patch will get merged right into Tor. [Assuming we're not
165 in the middle of a code-freeze window. If the codebase is
166 frozen, your patch will go into the next release series.]
168 * OR the reviewer will say "_looks good, just needs some small
169 changes!_" And then the reviewer will make those changes,
170 and merge the modified patch into Tor.
172 * OR the reviewer will say "_Here are some questions and
173 comments,_" followed by a bunch of stuff that the reviewer
174 thinks should change in your code, or questions that the
175 reviewer has.
177 At this point, you might want to make the requested changes
178 yourself, and comment on the trac ticket once you have done
179 so. Or if you disagree with any of the comments, you should
180 say so! And if you won't have time to make some of the
181 changes, you should say that too, so that other developers
182 will be able to pick up the unfinished portion.
184 Congratulations! You have now written your first patch, and gotten
185 it integrated into mainline Tor.