A couple of Git ideas: new branches, easier changelogs

[Roger Dingledine]

On Fri, Mar 05, 2010 at 12:02:08AM -0500, Nick Mathewson wrote:
> 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.

Works for me. There will be some rough edges as we try it out. For
example, will I find it simplest to have three repositories now rather
than two, each with .git/HEAD pointing to the appropriate branch? Doesn't
sound so bad.

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

We had previously used a TODO.021 file to keep track of what patches were
still undergoing testing before the backport. But I guess that approach
made more sense in svn-land than in git-land.

To complicate matters a little bit, we had previously talked of having
two phases of a stable: the first phase is soon after it comes out,
where we backport lots of fixes as we discover them. The second phase
starts a few months in, where we stop backporting all fixes and become
increasingly picky about what we backport -- basically only fixing bugs
that an increasing number of people are affected by, security bugs, and
bugs where functionality used to work for that user but doesn't anymore.

In a sense this idea is orthogonal to the above question about branches.
But in another sense, if we had been sticking to this schedule, we may
not have been motivated to fix our process. :)

Being more picky about what we backport also has the advantage that when
we try to get various distros to update their out-of-date packages in
stable, there are 3 changelog entries rather than 10. The timing usually
lines up too, in that we generally only find ourselves trying to get
people to update once the stable has been stable for a long time.

Speaking of best practice, the only way that this scheme is going to work
well is if I pick up the pace on releasing developent versions. And if
I do that, it will also help resolve some of the problems that required
us to be thinking about a third branch. So, I should do that. And you all
should encourage me to. :)

Here's a scenario I expect to happen: we have 15 items in maint-0.2.1,
5 of which are in release-0.2.1. Then we realize one of the remaining 10
is more urgent than we thought, and it's time for a stable release that
includes that patch even though it hasn't been in a development release
"long enough". So we cherry-pick it from maint-0.2.1 to release-0.2.1,
examine it very carefully, and release?

But even in that scenario, I agree it's better to not have all 15 items,
9 of which are not tested well, in the branch that we try to release.

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

I like B's advantage: I can incrementally prepare the changelog for
an upcoming release whenever I want to, not just at release time. And
then mere humans (aka those not using git) can see that in-progress
changelog too.

It's also my experience that people write better changelog entries when
they know they're writing a changelog entry. Writing a git commit message
is not writing a changelog entry. We could train ourselves to think of
them as the same thing, but training our developers to become different
is always harder than it sounds.

That said, we won't just be concatenating them in any case. People will
have to say what section of the changelog their text should go in, e.g.:
  o Minor bugfixes:
    - Work correctly out-of-the-box with even more vendor-patched versions
      of OpenSSL. In particular, make it so Debian and OS X don't need
      customized patches to run/build.

But that doesn't sound so bad.

Choice D would be a good choice if we were all developers, and all our
users who read the changelog were developers too. Everybody would want
to know the commit messages. I can imagine that's the case for the Linux
kernel. But that stopped being the case for Tor several years back.

--Roger