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

[Roger Dingledine]

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.

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.

I think the best answer we can hope for is scenario 1.

But it gets worse. We need to be sure to fold every changes/foo file into
maint-0.2.1's changelog before we merge to master, or it could turn into
scenario 2. So:

Scenario 4: Always make your maint-0.2.1 commits in pairs, one to make
changes/foo and another to delete it and fold it immediately into the
ChangeLog file. It will need to be manually added to the 0.2.2.x-alpha
ChangeLog file later in any case.

Scenario 5: Just go ahead and put your changes into the ChangeLog file
directly; this changes/foo business is only for master.

Is there any benefit to Scenario 4 over Scenario 5?

--Roger