Browse Source

Update hacking file with terse notes on formatting changelog

Nick Mathewson 14 years ago
parent
commit
676190e895
1 changed files with 33 additions and 0 deletions
  1. 33 0
      doc/HACKING

+ 33 - 0
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
 and as a directory authority. See if it has any obvious bugs, and
 resolve those.
 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
 2) Gather the changes/* files into a changelog entry, rewriting many
 of them and reordering to focus on what users and funders would find
 of them and reordering to focus on what users and funders would find
 interesting and understandable.
 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
 3) Compose a short release blurb to highlight the user-facing
 changes. Insert said release blurb into the ChangeLog stanza. If it's
 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
 a stable release, add it to the ReleaseNotes file too. If we're adding