New changelog system (developers please read) [was Re: A couple of Git ideas: new branches, easier changelogs]
arma at mit.edu
Sat Apr 3 18:27:14 UTC 2010
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
> When you do a commit that needs a ChangeLog entry, add a new file to
> the "changes" toplevel subdirectory.
> 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?
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?
More information about the tor-dev