On 8/30/13 4:01 AM, Branko Čibej wrote: > A log message should describe what changed in the code. Automatically > generating release notes and/or CHANGES from log messages is, in my > experience, quite impractical. A better approach would be to require the > CHANGES file to be updated in the same commit as the actual relevant > change. But even that's not realistic, because often such a change will > be split across several commits -- or, for example, developed on a branch.
I'm going to respond to Branko's email because he brings up some important points, but in general I'm replying to everyone. I agree completely automated generation is a not going to happen. My motivation is to just make the job easier. It can take a lot of time to figure out what to say to users when producing CHANGES. This is a much less ambitious goal than full automation. Making commits to CHANGES along side your other changes is a bad idea. Let me explain why: 1) Conflicts. CHANGES on trunk is drastically different than CHANGES on the branches. So it'll increase the hoop jumping we have to do to avoid conflicts when backporting changes. 2) Backporting. We are never really sure what we're going to backport. 1.9.x should not mention a change that was included in say 1.8.6. It's not a change from the user's perspective. So it's entirely unclear where you should add your data to the CHANGES file. Already the fact that we start putting 1.9.x CHANGES entries into trunk messes up release.py's attempt to detect unmerged CHANGES. I've changed that to a warning. I haven't objected to this practice because I think it makes sense to put things we know we'll never backport in CHANGES. But we also can't just start doing it all the time. We also can't require changes entries be attached to commits since sometimes we're commiting fixes to things that were never released in a broken state. So there is no effective change as far as a user is concerned. If you look at the 411 Content-Length issue I think any attempt to put the CHANGES entry in the log files would have been a mess. Putting details from the user perspective in the commit message is still helpful in that case, since the person nominating a change may not be the person who wrote the change. Also sometimes what we thought the user impact was at commit time is incomplete. We find many times where a change made for one reason fixes something else and we decide to backport it for that reason. So I felt that STATUS was a reasonable compromise for now.
