[tor-commits] [tor/master] Update hacking file with terse notes on formatting changelog

[nickm at torproject.org]

commit 676190e895a94978fbda82527f7ba2dbf8ccda80
Author: Nick Mathewson <nickm at torproject.org>
Date:   Thu Apr 28 23:44:48 2011 -0400

    Update hacking file with terse notes on formatting changelog
---
 doc/HACKING |   33 +++++++++++++++++++++++++++++++++
 1 files changed, 33 insertions(+), 0 deletions(-)

diff --git a/doc/HACKING b/doc/HACKING
index b612953..6407ff2 100644
--- a/doc/HACKING
+++ b/doc/HACKING
@@ -414,10 +414,43 @@ Here are the steps Roger takes when putting out a new Tor release:
 and as a directory authority. See if it has any obvious bugs, and
 resolve those.
 
+1.5) As applicable, merge the maint-X branch into the release-X branch.
+
 2) Gather the changes/* files into a changelog entry, rewriting many
 of them and reordering to focus on what users and funders would find
 interesting and understandable.
 
+   2.1) Make sure that everything that wants a bug number has one.
+   2.2) Concatenate them.
+   2.3) Sort them by section.  Within each section, try to make the
+      first entry or two and the last entry most interesting: they're
+      the ones that skimmers tend to read.
+
+   2.4) Clean them up
+
+   Standard idioms:
+     "Fixes bug 9999; Bugfix on 0.3.3.3-alpha."
+
+   One period after a space.
+
+   Make stuff very terse
+
+   Describe the user-visible problem right away
+
+   Mention relevant config options by name.  If they're rare or unusual,
+   remind people what they're for
+
+   Avoid starting lines with open-paren
+
+   Present and imperative tense: not past.
+
+   2.5) Merge them in.
+
+   2.6) Clean everything one last time.
+
+   2.7) Run it through fmt to make it pretty.
+
+
 3) Compose a short release blurb to highlight the user-facing
 changes. Insert said release blurb into the ChangeLog stanza. If it's
 a stable release, add it to the ReleaseNotes file too. If we're adding