Update hacking file with terse notes on formatting changelog

This commit is contained in:
Nick Mathewson 2011-04-28 23:44:48 -04:00
parent f0d9e2d650
commit 676190e895

View File

@ -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