A couple of Git ideas: new branches, easier changelogs

[Nick Mathewson]

On Fri, Mar 5, 2010 at 3:19 PM, Roger Dingledine <arma at mit.edu> wrote:
> 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.

It's up to you how you want to do it on your own working machines.  I
generally use a separate local working repositories only to the extent
I find it necessary to avoid re-running autoconf all the time.

 [...]

I'm skipping over stuff about "backporting less".  I agree that it's
mostly orthogonal...

...except for the point that it isn't always easy to see when you
start working on a bugfix how important it's really going to wind up
being.

One way to implement it might be, at some point late in the release
cycle, to stop merging maint-0.2.1 into release-0.2.1 entirely, and
_only_ cherry-pick.  That way we still have a queue of "what are the
bugfixes on 0.2.1"; but we _would_ have a tricky time keeping track of
what was or wasn't backported.

Or if we want to be more merge-friendly, when 0.2.1.x becomes old
news, we could say "Starting now, every fix on 0.2.1.x gets its own
branch.  Merge all such branches into maint-0.2.1 and master.  Merge
them into release-0.2.1 only when it seems most sensible."

I think these approaches are worth thinking about if the maint/release
thing starts becoming nonfunctional, but perhaps a bit too complicated
to do before then.

 [...]
> 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?

I believe that's so.  It beats our current approach, which has been
"release an 0.2.1.x version from maint-0.2.1 immediately and hope that
nothing vital got broken."

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

Well, we'll have to train people to generate new files in 'changes'
and give them names that are nice and distinct.  (In my experience,
the same people who don't write commit messages with communicative
intent are the same ones who won't write changelog messages unless you
threaten them and call them unkind names.)  But at least with B, it's
a little easier to write the changelog messages for them without
having to amend all their commits before merging them.

yrs,
-- 
Nick