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

[Nick Mathewson]

On Sat, Apr 3, 2010 at 2:27 PM, Roger Dingledine <arma at mit.edu> wrote:
> On Mon, Mar 08, 2010 at 11:49:06PM -0500, Nick Mathewson wrote:
>> 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.
> [snip]
>> 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.
>
> We just ran into an edge case for this new design: how do we handle
> changelog entries in maint-0.2.1?
>
> According to
> https://bugs.torproject.org/flyspray/index.php?do=details&id=1324&area=comments#4159
> Nick recommends using the changes/ approach in maint-0.2.1 too, "Or else
> when we merge it into master, there will be conflict fun."
>
> But that isn't going to do what we want.
>
> Scenario 1: I add a changes/foo file to maint-0.2.1. I add the entry
> into the maint-0.2.1 ChangeLog file, and delete changes/foo. We merge
> it into master. I'm going to have to manually copy entries from the
> 0.2.1.26 release into the appropriate 0.2.2.x-alpha release.
>
> Scenario 2: I add a change/foo file to maint-0.2.1, then we merge it to
> master. Then I delete it from maint-0.2.1 while building the 0.2.1.26
> changelog, and delete it from master while building the 0.2.2.x-alpha
> changelog. Then we'll have a conflict.

Actually, no.  Git doesn't mind if you delete the same thing (or
generally, if you make the same change) in two branches.  The merge
algorithm isn't completely broken. :)

> Scenario 3: We opt to never delete changes/foo in the maint-0.2.1 tree,
> so it will survive into master, so we can fold it into the 0.2.2.x-alpha
> changelog and then delete it there. But then the changes/ files just
> pile up in maint-0.2.1. That's no good.

Revised protocol (discussed on IRC):

Remember that we're planning to stop doing releases from maint-0.2.1
directly.  Instead, we're hoping to have a release-0.2.1 branch that
pulls from older versions of maint-0.2.1, plus from occasional hotfix
branches.  The idea was to ensure that bugfixes get tested for a good
while in master before they make it into a stable release.

Once this is done, the answer becomes clear (ish): edit changes
entries for clarity in maint-0.2.1.  Only
delete-and-merge-into-a-changelog when actually doing a release from
master or release-0.2.1.

Better?

-- 
Nick