New changelog system (developers please read) [was Re: A couple of Git ideas: new branches, easier changelogs]

[Nick Mathewson]

So it looks like we've settled on a new way to get good ChangeLogs
written without running into merge conflicts every time we turn
around, and without requiring that everybody's commit messages be
user-facing.

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, as in

   o Major bugfixes:
      - Fix a potential buffer overflow.  Fixes bug 9999.

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.

Frequently Unasked Questions:

1) What needs a changelog entry?

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.

2) What goes in a changelog entry?

First, categorize it.  Some common categories are:

    Minor bugfixes, Major bugfixes, Minor features, Major features,
Code simplifications and refactoring.

Then, say what the change does.

Finally, if it's a bugfix, then mention what bug it fixes and when the
bug was introduced.

3) What's the difference between a major bugfix and a minor bugfix, or
a major feature and a minor feature?

Use your own best judgment.

-- 
Nick