[tor-commits] [tor/master] Add my draft (in-progress) guide to getting started on tor development
nickm at torproject.org
nickm at torproject.org
Thu Oct 8 15:52:31 UTC 2015
Author: Nick Mathewson <nickm at torproject.org>
Date: Thu Oct 8 11:52:27 2015 -0400
Add my draft (in-progress) guide to getting started on tor development
doc/GettingStarted.txt | 207 ++++++++++++++++++++++++++++++++++++++++++++++++
doc/HACKING | 5 +-
doc/include.am | 3 +-
3 files changed, 213 insertions(+), 2 deletions(-)
diff --git a/doc/GettingStarted.txt b/doc/GettingStarted.txt
new file mode 100644
@@ -0,0 +1,207 @@
+Getting started in Tor development
+Congratulations! You've found this file, and you're reading it! This
+means that you might be interested in getting started in developing Tor.
+(This guide is just about Tor itself--the small network program at the
+heart of the Tor network--and not about all the other programs in the
+whole Tor ecosystem.)
+If you are looking for a more bare-bones, less user-friendly information
+dump of important information, you might like reading doc/HACKING
+instead. You should probably read it before you write your first patch.
+First, I'm going to assume that you can build Tor from source, and that
+you know enough of the C language to read and write it. (See the README
+file that comes with the Tor source for more information on building it,
+and any high-quality guide to C for information on programming.)
+I'm also going to assume that you know a little bit about how to use
+Git, or that you're able to fillow one of the several excellent guides
+at http://git-scm.org to learn.
+Most Tor developers develop using some Unix-based system, such as Linux,
+BSD, or OSX. It's okay to develop on Windows if you want, but you're
+going to have a more difficult time.
+Getting your first patch into Tor
+Once you've reached this point, here's what you need to know.
+ 1) Get the source.
+ We keep our source under version control in Git. To get the latest
+ version, run
+ git clone https://git.torproject.org/git/tor
+ This will give you a checkout of the master branch. If you're
+ going to fix a bug that appears in a stable version, check out the
+ appropriate "maint" branch, as in:
+ git checkout maint-0.2.7
+ 2) Find your way around the source
+ Our overall code structure is explained in the "torguts" documents,
+ currently at
+ git clone https://git.torproject.org/user/nickm/torguts.git
+ Find a part of the code that looks interesting to you, and start
+ looking around it to see how it fits together!
+ We do some unusual things in our codebase. Our testing-related
+ practices and kludges are explained in doc/WritingTests.txt.
+ If you see something that doesn't make sense, we love to get
+ 3) Find something cool to hack on.
+ You may already have a good idea of what you'd like to work on, or
+ you might be looking for a way to contribute.
+ Many people have gotten started by looking for an area where they
+ personally felt Tor was underperforming, and investigating ways to
+ fix it. If you're looking for ideas, you can head to our bug
+ tracker at trac.torproject.org and look for tickets that have
+ received the "easy" tag: these are ones that developers think would
+ be pretty simple for a new person to work on. For a bigger
+ challenge, you might want to look for tickets with the "lorax"
+ keyword: these are tickets that the developers think might be a
+ good idea to build, but which we have no time to work on any time
+ Or you might find another open ticket that piques your
+ interest. It's all fine!
+ For your first patch, it is probably NOT a good idea to make
+ something huge or invasive. In particular, you should probably
+ * Major changes spread across many parts of the codebase.
+ * Major changes to programming practice or coding style.
+ * Huge new features or protocol changes.
+ 4) Meet the developers!
+ We discuss stuff on the tor-dev mailing list and on the #tor-dev
+ IRC channel on OFTC. We're generally friendly and approachable,
+ and we like to talk about how Tor fits together. If we have ideas
+ about how something should be implemented, we'll be happy to share
+ We currently have a patch workshop at least once a week, where
+ people share patches they've made and discuss how to make them
+ better. The time might change in the future, but generally,
+ there's no bad time to talk, and ask us about patch ideas.
+ 5) Do you need to write a design proposal?
+ If your idea is very large, or it will require a change to Tor's
+ protocols, there needs to be a written design proposal before it
+ can be merged. (We use this process to manage changes in the
+ protocols.) To write one, see the instructions at
+ . If you'd like help writing a proposal, just ask! We're happy to
+ help out with good ideas.
+ You might also like to look around the rest of that directory, to
+ see more about open and past proposed changes to Tor's behavior.
+ 6) Writing your patch
+ As you write your code, you'll probably want it to fit in with the
+ standards of the rest of the Tor codebase so it will be easy for us
+ to review and merge. You can learn our coding standards in
+ If your patch is large and/or is divided into multiple logical
+ components, remember to divide it into a series of Git commits. A
+ series of small changes is much easier to review than one big lump.
+ 7) Testing your patch
+ We prefer that all new or modified code have unit tests for it to
+ ensure that it runs correctly. Also, all code should actually be
+ _run_ by somebody, to make sure it works.
+ See doc/WritingTests.txt for more information on how we test things
+ in Tor. If you'd like any help writing tests, just ask! We're
+ glad to help out.
+ 8) Submitting your patch
+ We review patches through tickets on our bugtracker at
+ trac.torproject.org. You can either upload your patches there, or
+ put them at a public git repository somewhere we can fetch them
+ (like github or bitbucket) and then paste a link on the appropriate
+ trac ticket.
+ Once your patches are available, write a short explanation of what
+ you've done on trac, and then change the status of the ticket to
+ 9) Review, Revision, and Merge
+ With any luck, somebody will review your patch soon! If not, you
+ can ask on the IRC channel; sometimes we get really busy and take
+ longer than we should. But don't let us slow you down: you're the
+ one who's offering help here, and we should respect your time and
+ When your patch is reviewed, one of these things will happen:
+ * The reviewer will say "looks good to me" and your
+ patch will get merged right into Tor. [Assuming we're not
+ in the middle of a code-freeze window. If the codebase is
+ frozen, your patch will go into the next release series.]
+ * OR the reviewer will say "looks good, just needs some small
+ changes!" And then the reviewer will make those changes,
+ and merge the modified patch into Tor.
+ * OR the reviewer will say "Here are some questions and
+ comments," followed by a bunch of stuff that the reviewer
+ thinks should change in your code, or questions that the
+ reviewer has.
+ At this point, you might want to make the requested changes
+ yourself, and comment on the trac ticket once you have done
+ so. Or if you disagree with any of the comments, you should
+ say so! And if you won't have time to make some of the
+ changes, you should say that too, so that other developers
+ will be able to pick up the unfinished portion
+ Congratulations! You have now written your first patch, and gotten
+ it integrated into mainline Tor.
+Where do I go from here?
+The design paper
+XXXX describe these and add links.
diff --git a/doc/HACKING b/doc/HACKING
index e92d675..5a1454e 100644
@@ -1,7 +1,7 @@
Hacking Tor: An Incomplete Guide
For full information on how Tor is supposed to work, look at the files in
@@ -19,6 +19,9 @@ discussion belong on the tor-dev mailing list. We hang around on
irc.oftc.net, with general discussion happening on #tor and development
happening on #tor-dev.
+For a nice quick-start guide to hacking on Tor, have a look at
+doc/GettingStarted.txt, included with the Tor distribution.
How we use Git branches
diff --git a/doc/include.am b/doc/include.am
index 41d3d2a..f33103b 100644
@@ -39,7 +39,8 @@ EXTRA_DIST+= doc/HACKING doc/asciidoc-helper.sh \
+ doc/WritingTests.txt \
docdir = @docdir@
More information about the tor-commits