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.
Regards,
Graham
--
