From 8ec5f939a6dd48d93ab5535b207e454b0b990ab3 Mon Sep 17 00:00:00 2001 From: Nick Mathewson Date: Tue, 20 Apr 2010 00:52:34 -0400 Subject: Add new sections to the HACKING file The main changes are to explain how we use git branches, how we use changes files, and what should go into a patch. Putting these in HACKING means that we shouldn't need to constantly refer to the or-dev emails where we explain this stuff. --- doc/HACKING | 135 +++++++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 119 insertions(+), 16 deletions(-) (limited to 'doc/HACKING') diff --git a/doc/HACKING b/doc/HACKING index 9f477c61d..70bda65ab 100644 --- a/doc/HACKING +++ b/doc/HACKING @@ -1,27 +1,111 @@ Hacking Tor: An Incomplete Guide ================================ +Getting started +--------------- + +For full information on how Tor is supposed to work, look at the files in +doc/spec/ . + +For an explanation of how to change Tor's design to work differently, look at +doc/spec/proposals/001-process.txt . + +For the latest version of the code, get a copy of git, and + + git clone git://git.torproject.org/git/tor . + +We talk about Tor on the or-talk mailing list. Design proposals and +discussion belong on the or-dev mailing list. We hang around on +irc.oftc.net, with general discussion happening on #tor and development +happening on #tor-dev. + +How we use Git branches +----------------------- + +Each main development series (like 0.2.1, 0.2.2, etc) has its main work +applied to a single branch. At most one series can be the development series +at a time; all other series are maintenance series that get bug-fixes only. +The development series is built in a git branch called "master"; the +maintenance series are built in branches called "maint-0.2.0", "maint-0.2.1", +and so on. We regularly merge the active maint branches forward. + +For all series except the development series, we also have a "release" branch +(as in "release-0.2.1"). The release series is based on the corresponding +maintenance series, except that it deliberately lags the maint series for +most of its patches, so that bugfix patches are not typically included in a +maintenance release until they've been tested for a while in a development +release. Occasionally, we'll merge an urgent bugfix into the release branch +before it gets merged into maint, but that's rare. + +If you're working on a bugfix for a bug that occurs in a particular version, +base your bugfix branch on the "maint" branch for the first _actively +developed_ series that has that bug. (Right now, that's 0.2.1.) If you're +working on a new feature, base it on the master branch. + + +How we log changes +------------------ + +When you do a commit that needs a ChangeLog entry, add a new file to +the "changes" toplevel subdirectory. It should have the format of a +one-entry changelog section from the current ChangeLog file, as in + + o Major bugfixes: + - Fix a potential buffer overflow. Fixes bug 9999. Bugfix on + Tor 0.3.1.4-beta. + +To write a changes file, first categorize the change. Some common categories +are: Minor bugfixes, Major bugfixes, Minor features, Major features, Code +simplifications and refactoring. Then say what the change does. Then, if +it's a bugfix, then mention what bug it fixes and when the bug was +introduced. + +If at all possible, try to create this file in the same commit where +you are making the change. Please give it a distinctive name that no +other branch will use for the lifetime of your change. + +When Roger goes to make a release, he will concatenate all the entries +in changes to make a draft changelog, and clear the directory. He'll +then edit the draft changelog into a nice readable format. + +What needs a changes file?:: + A not-exhaustive list: Anything that might change user-visible + behavior. Anything that changes internals, documentation, or the build + system enough that somebody could notice. Big or interesting code + rewrites. Anything about which somebody might plausibly wonder "when + did that happen, and/or why did we do that" 6 months down the line. + +Why use changes files instead of Git commit messages?:: + Git commit messages are written for developers, not users, and they + are nigh-impossible to revise after the fact. + +Why use changes files instead of entries in the ChangeLog?:: + Having every single commit touch the ChangeLog file tended to create + zillions of merge conflicts. Useful tools ------------ +These aren't strictly necessary for hacking on Tor, but they can help track +down bugs. + The buildbot ~~~~~~~~~~~~ https://buildbot.vidalia-project.net/one_line_per_build -Useful command-lines -~~~~~~~~~~~~~~~~~~~~ - Dmalloc -^^^^^^^ +~~~~~~~ + +The dmalloc library will keep track of memory allocation, so you can find out +if we're leaking memory, doing any double-frees, or so on. -dmalloc -l ~/dmalloc.log -(run the commands it tells you) -./configure --with-dmalloc + dmalloc -l ~/dmalloc.log + (run the commands it tells you) + ./configure --with-dmalloc Valgrind -^^^^^^^^ +~~~~~~~~ valgrind --leak-check=yes --error-limit=no --show-reachable=yes src/or/tor @@ -30,7 +114,7 @@ pass --undef-value-errors=no to valgrind, or rebuild your openssl with -DPURIFY.) Running gcov for unit test coverage -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----- make clean @@ -48,6 +132,24 @@ of times. Coding conventions ------------------ +Patch checklist +~~~~~~~~~~~~~~~ + +If possible, send your patch as one of these (in descending order of +preference) + + - A git branch we can pull from + - Patches generated by git format-patch + - A unified diff + +Did you remember... + + - To build your code while configured with --enable-gcc-warnings? + - To run "make check-speces" on your code? + - To write unit tests, as possible? + - To base your code on the appropriate branch? + - To include a file in the "changes" directory as appropriate? + Whitespace and C conformance ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -78,8 +180,7 @@ the compiler, and help us find divergences from our preferred C style. Getting emacs to edit Tor source properly ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Hi, folks! Nick here. I like to put the following snippet in my .emacs -file: +Nick likes to put the following snippet in his .emacs file: ----- (add-hook 'c-mode-hook @@ -111,7 +212,7 @@ what they want. If you want to try this out, you'll need to change the filename regex patterns to match where you keep your Tor files. -If you *only* use emacs to edit Tor, you could always just say: +If you use emacs for editing Tor and nothing else, you could always just say: ----- (add-hook 'c-mode-hook @@ -125,11 +226,13 @@ If you *only* use emacs to edit Tor, you could always just say: There is probably a better way to do this. No, we are probably not going to clutter the files with emacs stuff. -Details -~~~~~~~ -Use tor_malloc, tor_free, tor_strdup, and tor_gettimeofday instead of their -generic equivalents. (They always succeed or exit.) +Functions to use +~~~~~~~~~~~~~~~~ + +We have some wrapper functions like tor_malloc, tor_free, tor_strdup, and +tor_gettimeofday; use them instead of their generic equivalents. (They +always succeed or exit.) You can get a full list of the compatibility functions that Tor provides by looking through src/common/util.h and src/common/compat.h. You can see the -- cgit v1.2.3