apr-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jeff Trawick <traw...@gmail.com>
Subject Re: svn commit: r822263 - /apr/apr-util/branches/1.4.x/CHANGES
Date Tue, 13 Oct 2009 13:14:54 GMT
On Tue, Oct 13, 2009 at 8:22 AM, Graham Leggett <minfrin@sharp.fm> wrote:
> Jeff Trawick wrote:
>> My understanding: Each of these deleted entries thus far is a minor
>> implementation detail related to the new apr_crypto feature.  As the
>> feature was never released, they do not fix a problem for the users of
>> our library.  OTOH, any of these if tied to a particular user symptom
>> could be interesting in the change log for a bug fix release, such as
>> 1.4.1.
> Now that I have some time to draft a proper reply.
> The argument that "the feature was never released" becomes moot the
> moment the code is released, and that will happen when we ship APR
> v1.4.0 (or APR v2.0.0).

You're not understanding what I'm attempting to say.  The distinction
of whether or not the feature was released and how that affects the
necessary change entries is exemplified by the following:

If apr_crypto in future APR-util 1.4 had some problem like not finding
nss.h in all the possible locations and that broke the apr_crypto
feature for somebody and it was fixed in the .1 release, then the .1
release would list the fix in CHANGES.

If such a problem was found before apr_crypto was released, the fix is
just part of the initial delivery and doesn't need to be in changes.

> At that point, end users are going to want to know what's changed
> between the last release and this one. And in the case of APR v2.0.0,
> people are *really* going to want to know what has changed.
> More specifically, people are going to want to know exactly how that
> change got there, and that feature morphed over time to become what it
> is now.

I don't agree.  I also don't think trivial stuff like how to find
nss.h, for example, is a morphing of a feature.

> What you're arguing for is a "dumbed down" version of CHANGES, where
> only a general announcement of a feature is included, but the core
> details of how the feature got there are erased. And I'm firmly opposed
> to that.

The idea I'm trying to state is that CHANGES should be limited to
listing new features or fixes for problems that existed in the
previous release.  I don't think that is dumbed down.  CHANGES is end
user documentation.

Subversion history covers the trail from first commit to the present.

> CHANGES isn't a marketing brochure, it's the thing that will show up in
> google searches when end users are trying to debug a problem. And we can
> fully expect problems to found when APR v2.0.0 is released, and people
> to want to fix them.

I don't see your point.  Are you saying that if apr_crypto isn't
enabled for somebody trying to use 1.4 because it can't find some
OpenSSL or NSS artifact, then they should be able to find in CHANGES
that other similar problems were fixed before 1.4 was released?

The intended use of CHANGES in resolving a problem is to show which
problem symptoms in previous releases have been corrected.

> There is a further, deeper reason why I oppose these changes to CHANGES
> - the changes documented were committed 18 months ago. Without having
> recent memory to go by, we are arbitrarily chopping out sections of our
> history based in whether an entry looks "important" or not. We are
> changing our historical record, and that is a really bad idea.

Use Subversion history.

> We have no idea what information might be vital to an end user to solve
> a particular problem they have. An innocuous looking change could be the
> cause of a bug. And no, end users of the library aren't going to be
> checking out apr from svn to try and find the history.

CHANGES is not for solving new problems.  It is for recording what was
fixed or enhanced in released levels of APR.

> We certainly should not be making end user's lives more difficult for
> the sake of saving a few bytes.

This is not about saving a few bytes.  It is about getting needless
implementation details out of the documentation.

> On this basis, my -1 stands. Please revert the CHANGES (so to speak).

You cannot veto documentation.

You should follow the group consensus in what sort of details are
included in CHANGES.  If you look at the entries for the unreleased
levels of APR and APR-util, you won't find any trail of iterations for
any of the new features, even though some was required to get it
building everywhere and fixing initial problems.  Also, recall that
two other developers approved my editing of the trail for the new
apr_crypto feature before I committed.

Including these details in CHANGES is unsustainable.  CHANGES would be
completely unusable if these iterative fixes for new features were
included.  The few people who need to know this kind of information
will have to get it from Subversion history.

View raw message