[or-cvs] [tor/master 2/2] Add new sections to the HACKING file

Tue Apr 27 16:26:50 UTC 2010

Author: Nick Mathewson <nickm at torproject.org>
Date: Tue, 20 Apr 2010 00:52:34 -0400
Subject: Add new sections to the HACKING file
Commit: 8ec5f939a6dd48d93ab5535b207e454b0b990ab3

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.
---
 changes/revise_HACKING |    4 ++
 doc/HACKING            |  135 ++++++++++++++++++++++++++++++++++++++++++------
 2 files changed, 123 insertions(+), 16 deletions(-)
 create mode 100644 changes/revise_HACKING

diff --git a/changes/revise_HACKING b/changes/revise_HACKING
new file mode 100644
index 0000000..7cc68a1
--- /dev/null
+++ b/changes/revise_HACKING
@@ -0,0 +1,4 @@
+ o Documentation:
+   - Convert the HACKING file to asciidoc, and add a few new sections
+     to it, explaining how we use Git, how we make changelogs, and
+     what should go in a patch.
diff --git a/doc/HACKING b/doc/HACKING
index 9f477c6..70bda65 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
-- 
1.6.5

