commit 676190e895a94978fbda82527f7ba2dbf8ccda80 Author: Nick Mathewson <nickm@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