1 files changed, 187 insertions, 0 deletions
diff --git a/doc/HACKING/GettingStarted.md b/doc/HACKING/GettingStarted.md
new file mode 100644
index 0000000000..0295adc1ff
--- /dev/null
+++ b/doc/HACKING/GettingStarted.md
@@ -0,0 +1,187 @@
+
+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.
+
+
+Required background
+-------------------
+
+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 follow 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
+     questions!
+
+  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
+     soon.
+
+     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
+     avoid:
+
+       * 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
+     them.
+
+     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
+     https://gitweb.torproject.org/torspec.git/tree/proposals/001-process.txt
+     .  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
+     doc/HACKING.
+
+     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
+     needs_review.
+
+  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
+     contributions.
+
+     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.