A couple of Git ideas: new branches, easier changelogs

[Nick Mathewson]

PART 1: new branches

In the wake of the embarrassingly stupid bug 1269, I talked with Roger
and some other developers for a while about how we can use git better
to make sure that bugfixes only get backported to the stable branch
when they are well and truly tested.

Right now, we've been doing this in a couple of ways, both of which
are pretty bad in practice.  Sometimes we do fixes and merge them to
the master branch first, then backport them to the 0.2.1 branch via
cherry-picking once they've been around for a while.  This approach
risks losing track of patches, though, unless we keep close watch on
what fixes have happened where.  Sometimes we merge "obvious" fixes
into the 0.2.1 branch, and regularly merge 0.2.1 into master.
Unfortunately, "obvious" fixes can be broken too easily.

So here's what I propose.  We create a new "release-0.2.1" branch
based on maint-0.2.1, and do all our releases off that branch.  We do
_all_ bugfixes of 0.2.1 bugs in the maint-0.2.1 branch, which we merge
into master regularly.  We don't merge maint-0.2.1 directly into
release-0.2.1, however: instead, we tag it whenever we do a release of
0.2.2 from the master branch.  Only once the 0.2.2 version has tested
for a while do we merge maint-0.2.1 into release-0.2.1.  This way,
bugfixes get tested for a while in the alpha before they get merged
into stable, and we don't need to worry about losing track of them.

Not everything can be tested for a long time in the alpha before a
backport.  Notable exceptions are:
   1) fixes to bugs that only exist in the stable series
   2) critical bugs that need to get fixed Right Away.

For these, we should have a separate branch or two; I'm not sure what
to call them.

I think the above plan is an improvement, but I'm sure it's not
optimal.  Keeping the bikeshed in mind, are there better ideas, or
ways to do this better?

PART 2:

Git merges have been working really nicely for us, with one exception:
our changlog file.  Nearly every merge creates a conflict in the
changelog, and more work for the merger.  Worse, if somebody starts
working on a feature that doesn't get merged until after a release
occurs, their feature's changelog entry usually tries to merge itself
into the previous version's changelog section, not into the new
changelog stuff where it belongs.

If we do more parallel branches, merging will just get nastier.

Here are some options:
   A) Do nothing.
   B) Instead of creating a changelog entry, commits that want to add
something to the changelog should add a file to a "changes" directory,
whose elements get concatenated into a changelog before a release.
[weasel suggested this one.]
   C) Commit messages should try to be written so they themselves can
be turned into changelog entries.  To generate a changelog, just run
git log previous-release..master and massage the output.
   D) Like C, except recognizing that some commits don't warrant
independent changelog entries... so we add a way to annotate commits
(e.g., with a footer line) to say "This doesn't go in the changelog!"
or "This goes in the changelog in the new features section!"  Only
unannotated commits would need to get manually triaged.  We'd want a
little script to massage the git log into a draft changelog.

B and D seem like our best options to me.  B has the advantage that
it's easier to add or massage changelog entries between adding them
and the release; D has the advantage that we can't _forget_ to add a
changelog entry for anything.

-- 
Nick