Re: FYI: use api version

[Alexandre Duret-Lutz]

>>> "Tom" == Tom Tromey <address@hidden> writes:

 >>>>>> "adl" == Alexandre Duret-Lutz <address@hidden> writes:
 adl> I'm very sceptic about this.  The current definition
 adl> APIVERSION=`echo "$VERSION" | sed -e 's/^\([[0-9]]*\.[[0-9]]*\).*$/\1/'`
 adl> means that 1.5 1.5a 1.5b 1.5c 1.5d 1.5e will all be API-compatible.

 Tom> I thought about that briefly but didn't do anything about it.
 Tom> This is a bit problematic because our versioning scheme is a bit
 Tom> goofy.  We use `1.5b' to mean both "prerelease for 1.5.1" and
 Tom> "prerelease for 1.6".

 Tom> One idea would be to change our approach to numbering.

Presently it's not that bad: branch-real-1-5 uses 1.5.1a, so
including anything before the second dot in the API version
doesn't appear to conflict.

 adl> If 1.5e is the last version before 1.6, makes only documentation
 adl> changes, and is API-compatible with 1.5, I don't understand why
 adl> 1.6 is not deemed compatible with 1.5.

 Tom> Exactly :-(.
 Tom> This may require a process fix and not a code fix, on our end.
 Tom> Or maybe something else.  Any suggestions?

I'd say:

1) change the API version for any version released from HEAD,
   including prereleases, because one can't guaranty something he
   is unable to check (API compatibility).

2) keep the same API version for any bug fix release, but be
   very picky about what goes on these branches.  Especially,
   that means that not *all* bugs can be fixed in a bug fix
   release, and maybe a fix should even be reversed if
   s.o. discovers it breaks the API.  The fix for ar.test is an
   exemple of change which should not be allowed on bug fixes
   releases (see below).

3) document what is part of the API, and what isn't.  (That's
   probably the hardest.)

[...]

 adl> (Actually, that's not clear to me if this will always works.  To
 adl> play the devil's advocate: is fixing a bug someone relies on
 adl> considered an API breakage?)

 Tom> Well, hopefully this will put some evolutionary pressure on the
 Tom> documentation.  I agree there are grey areas here.  But there are also
 Tom> cases which are unambiguous, and we can aim to reduce ambiguity by
 Tom> changing the documentation to reflect what we know to be invalid (but
 Tom> which the users may not).

For instance, one area the documentation is completly fuzzy
about (IMHO) is the namespace Automake reserves for 
  * its internal use (am__*, *-am, etc.)
  * the interface with the user

For instance, the manual says that if `bin_PROGRAMS = maude' you
can use `maude_LDFLAGS = mumble' (who is maude, btw?), but it
doesn't say whether Automake reserves the whole `*_LDFLAGS'
namespace for this purpose or not.

I'm appending two test cases to this mail: acsubst.test and
acsubst2.test.  This is the 1.5b -> 1.5c failure I mentioned in
my previous mail (I think it is caused by the fix for ar.test.)

Both works fine with Automake 1.5b.  However `acsubst.test'
fails with 1.5c, whereas `acsubst2.test' still works with 1.5c;
meaning that 1.5c disallows people from AC_SUBSTing orphan
*_LDFLAGS variables, but still allow them to AC_SUBT orphan
*_CFLAGS variables.

(By `orphan' I mean there is no target associated to the
variable.  I find Automake's wording of `unused' to be
confusing, because in these test cases the variables *are*
used.)

[...]
-- 
Alexandre Duret-Lutz

acsubst.test
Description: Text document

acsubst2.test
Description: Text document