diff options
Diffstat (limited to 'doc/HACKING/GettingStarted.md')
| -rw-r--r-- | doc/HACKING/GettingStarted.md | 74 |
1 files changed, 33 insertions, 41 deletions
diff --git a/doc/HACKING/GettingStarted.md b/doc/HACKING/GettingStarted.md index 0c42404634..633a7f0417 100644 --- a/doc/HACKING/GettingStarted.md +++ b/doc/HACKING/GettingStarted.md @@ -1,23 +1,19 @@ - -Getting started in Tor development -================================== +# 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 +(_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.) - +whole Tor ecosystem._) If you are looking for a more bare-bones, less user-friendly information -dump of important information, you might like reading the "torguts" -documents linked to below. You should probably read it before you write +dump of important information, you might like reading the +[doxygen output](https://src-ref.docs.torproject.org/tor/index.html). +You probably should skim some of the topic headings there before you write your first patch. - -Required background -------------------- +## 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 @@ -26,22 +22,20 @@ 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. +at [git-scm](https://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 +Most Tor developers develop using some Unix-based system, such as GNU/Linux, +BSD, or macOS. 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 ---------------------------------- +## 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 + version, run: git clone https://git.torproject.org/git/tor @@ -49,20 +43,18 @@ Once you've reached this point, here's what you need to know. 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 + git checkout maint-0.4.3 - Our overall code structure is explained in the "torguts" documents, - currently at + 2. Find your way around the source. - git clone https://git.torproject.org/user/nickm/torguts.git + Our overall code structure is explained in our + [source documentation](https://src-ref.docs.torproject.org/tor/index.html). 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. + practices and kludges are explained in `doc/HACKING/WritingTests.md`. If you see something that doesn't make sense, we love to get questions! @@ -74,10 +66,10 @@ Once you've reached this point, here's what you need to know. 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 + fix it. If you're looking for ideas, you can head to + [trac](https://trac.torproject.org) our bug tracking tool 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 @@ -96,7 +88,7 @@ Once you've reached this point, here's what you need to know. 4. Meet the developers! - We discuss stuff on the tor-dev mailing list and on the #tor-dev + 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 @@ -113,8 +105,8 @@ Once you've reached this point, here's what you need to know. 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 + [the Tor proposal process](https://gitweb.torproject.org/torspec.git/plain/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 @@ -125,7 +117,7 @@ Once you've reached this point, here's what you need to know. 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. + `doc/HACKING` directory. If your patch is large and/or is divided into multiple logical components, remember to divide it into a series of Git commits. A @@ -137,16 +129,16 @@ Once you've reached this point, here's what you need to know. 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 + See `doc/HACKING/WritingTests.md` 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 + [trac](https://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 + (like gitlab, github or bitbucket) and then paste a link on the appropriate trac ticket. Once your patches are available, write a short explanation of what @@ -163,17 +155,17 @@ Once you've reached this point, here's what you need to know. When your patch is reviewed, one of these things will happen: - * The reviewer will say "looks good to me" and your + * 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, + * 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 + * 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. |