doc/HACKING/GettingStarted.md

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