On 15.06.2010 23:20, Graham Leggett wrote:
On 15 Jun 2010, at 4:21 PM, Jeff Trawick wrote:trunk CHANGES needs to track fixes/enhancements since the last alpha, so the candidates for pruning would be in the section "Changes with Apache 2.3.0". attached is a patch to prune 2.3.0 changes which were backported to some 2.2.x release; look reasonable? something that would make future-2.4 CHANGES more usable would be to collapse stuff like {"introduce mod_foo", "fix bug1 in mod_foo", "fix bug2 in mod_foo", "make enhancement1 to mod_foo"} within the same release into one mod_foo entry, and to axe entries which are for implementation details that users don't care about (or at least, if there is an external implication then document that and not the implementation detail) <2.3.0-backports.txt>Are we not going overboard on pruning the CHANGES file? Wearing my end user hat, had I been brave and installed v2.3.5, and wanted to consider v2.3.6, I'm going to download the tarball, open it up, and look at the CHANGES file. Where I won't find a complete list of changes between v2.3.5 and v2.3.6. The kicker of course is that I won't know these changes are missing, after all, I am a brave webmaster, not a C coder or a developer, I don't subscribe to the dev list, and I haven't read this or any other thread on this issue, and the CHANGES file has been around for over a decade, and there is no reason to suspect it works differently. Of course, you might include a sentence at the top of CHANGES saying "some changes have been backported to v2.2". Trouble is, which changes? Which changes were backported before v2.3.5 was released? Which after? No idea. I entirely understand the idea behind pruning the CHANGES file of entries older than the point at which trunk was branched to form v2.2, to ensure CHANGES did not grow boundlessly. A simple "this file continues on this branch" did the trick, and CHANGES file resets to zero size, and we start again. By way of comparison, here is the CHANGES file in httpd v2.2, which contains lots of entries over the life of the branch, and can be assumed to be large: -rw-r--r-- 1 minfrin 501 108719 Jun 6 01:48 CHANGES And here is our configure script: -rwxr-xr-x 1 minfrin 501 654523 Sep 23 2009 configure I don't see any benefit in attempting to shorten this file any further, given that it is short enough already. A clear and unambiguous CHANGES file is something useful to end users, however the current CHANGES file has holes in it, and is as a result of no use to end users at all.
All that has been pruned now was changes pre 2.3.*0* which have been backported. So this part of history is no longer relevant. Entries younger than 2.3.0 have *not* been pruned, even if backported.
I agree with Jeff, that 2.4.0 should start with a different granularity of historic change information. E.g. bugs only fixed durng the 2.3.x life in new modules are not really relevant for the 2.4 user. If he likes he can dig into the old 2.3 change file, but as a new 2.4 user he would only like to know what the new modules are and what they provide. but that's maybe a "What's new in 2.4" type docs page.
Rainer
