Re: obsoleted vs acinclude tool / Re: Masterplan

[Guido Draheim]

... going bottom up ;-)

> P. S.: Please do not Cc postings to the list to me directly when
>        replying, because I will receive them twice then.
>

That's a result of the mailer - there are two buttons, one is
"reply" and the other is "reply all". The first uses the
address in "From" - that would be you and not the list. The
other uses both addresses, From and To. That makes for
double. I do receive a lot of doubled mailing via autoconf
discussions, just because it is unsure whether the sender
is subscribed - and there are too many mailinglists that
I am subscribed to, well, I am somewhat low in trying to
remember which one is better to reply-all, and which ones
need to reply-all with editing the from-sender away.

>
>  > [...] sometimes a user wishes to rename a macro, or perhaps that is
>  > just a result of the wish to modify the call-synopsis or behaviour
>  > slightly. The old macro is not invalid by that, but it shall be
>  > moved out of being used in the current projects.
>
> This is an interesting problem. Here comes more policy:
>
>     Updates to already accepted macros MUST NOT break backwards
>     compatibility. If the new version has to be used in an in
>     different way than the original version, or if the new version
>     produces its results in a different way than the original version,
>     the author must submit the update under a new macro name. The
>     original version will be obsoleted.
>
>
> This raises another interesting question: If we enforce this kind of
> policy, do we any longer _need_ the macro to have a "version" string?
>
>

Yes! the difference is not so much about to "break" any usage,
the ac-archive macros should better be known to be a bit under
test and possibly to change slightly. The thing is about the
'documented behaviour'. If that thing changes, it shall better
be in another macro.

Let's make up an example - suppose there is a macro that like
AX_CFLAGS_NO_WRITEABLE_STRINGS, and it is documented to try
to add C compiler options to the CFLAGS that will make for
readonly-strings. Actually, almost all the compilers have a
different idea about that - only _warn_ about possible nonconst
usage of strings, to make it an _error_ and stop compiling, or
to make them into a readonly segment of the executable, so even
that the compiler warns and finished compiling, the executable
might segfault if the string was used nonconst for real.

While developing the ac-macro, the implementation might
change slightly - non-clean projects might break in consequence
but that is due to that project and not the intent of the
ac-macro in the first place.

Apart from those intentional changes, it might even be for
unintional ones - like adding a bugfix to the macro that
breaks some other project, like changing the implementatoin
like adding AC_LANG_C that would suddenly make it behave
different in mixed C/C++ projects, or slightly expanding
sanity checks that hits at some platform that run through
just before.

All these can be expressed with a "version number" of the
macro - it is specifically needed when handling bug reports
from other people, so that the developer can know whether
it is known or even fixed in the latest version. Or there
is a bug report about the newest breed along with a
version number of the last one where everything did work.

To summarize: a change in a macro SHALL try to not break
backward compatibility unless there is a verrry good reason
to do so. When it shall change for a new scheme, that is
supposed to be better, then make up a new name and mark
the old one as obsoleted, pointing to the new name of
the new variant. After some time, the old name is
deleted for real and the name again free to be used.

> Or do we just delete it?
>
>     In addition, macros in the "Obsolete" category will be marked as
>     being obsolete in the description and in the m4 source code, in
>     order to allow tools like acinclude or aclocal to recognize them
>     and to warn the user about it. The obsoletion marker will state
>     one of the following reasons:
>
>         * Has been replaced by 'foobar'.
>
>         * Has been included in the Autoconf distribution as 'barfoo'.
>
>         * Known deficits.
>
>     More detailed reasoning might be added to the macro's description
>     by the maintainer.
>

The "reason", well, that could be much more complicated, atleast it
should be flagged as obsolete - so to put pressure on the developers
who used the autoconf extension in a project to better change to
the new style - whatever that "new style" actually is. It could even
be that it is simply obsoleted because real world experiences did
show that it is better to use another and existing macro in a way
that was not being throught of when the macro was submitted. The
latest autoconf package is _huge_ in terms of providing helpers,
even that AS_ names might not be documented everywhere, or supposed
to stay constant at all time. (I use AS_DIRNAME and AS_MKDIR_P
quite often).

Anyway, here is a real world example as it works with the latest
sfnet release:

$ autotools
2.52-1.4.2-1.5 : acinclude (acinclude.m4)
acinclude: configure.ac: 41: `AC_COMPILE_WARNINGS' ...
... works but consider using AX_CFLAGS_WARN_ALL
acinclude: configure.ac: 424: `AC_PROG_CC_NO_WRITEABLE_STRINGS' ...
... obsoleted by AX_CFLAGS_NO_WRITABLE_STRINGS
acinclude: configure.ac: 425: `AC_PROG_CC_STRICT_PROTOTYPES' ...
... obsoleted by AX_CFLAGS_STRICT_PROTOTYPES
acinclude: configure.ac: 427: `AC_PROG_CC_WARNINGS' ...
... obsoleted - renamed to VL_PROG_CC_WARNINGS - or use AX_CFLAGS_WARN_ALL
acinclude: configure.ac: 506: `AC_CREATE_PREFIX_CONFIG_H' ...
... obsoleted by AX_PREFIX_CONFIG_H

These messages are triggered by "dnl obsolete <whatever>" entries in
the macro header - just the "dnl" is replaced with "..." and the
rest printed as is :-)=)

dnl @synposis AC_CREATE_PREFIX_CONFIG_H (.....)
dnl obsoleted by AX_PREFIX_CONFIG_H

Peter Simons schrieb:
> Guido Draheim writes:
>
>  > [obsolete macros]
>
> I am summarizing your points into policy:
>
>     We add a category "Obsolete", into which macros that have been
>     obsoleted will be moved. They will not disappear from either the
>     index or the distribution.
>
>     After moving them, we add an expiry date to the macro so that we
>     don't carry around baggage for all eternity. When the macro
>     expires, we move it into a "History" section that is not included
>     in the distribution. 

aaaahm, that was not my words but nethertheless a valid opinion
we see herein. Perhaps it turns out to be two phases when
obsoleting macros.

- "obsolete", marked as that but still in the (category) index pages
              and the release tarballs.
- "historic", removed from indexes but still accessible and only
              referenced from the "historic" category. It is not
              anymore redistributed in release tarballs.
-  deleted finally.

I do not know whether there is actually a need to add an expiry
date, but it might help still, and it makes some maintainers or
administrators happy when they know "when" it will be lost for
their current project. I could live well without a specific
date if it is around for atleast a year after the decision to
bring into the deletion phases - a note in the release tarball
changelist is more important to me.

Oh, and by the way - I would call the two phases indeed as
"obsolete" (to warn the user but still redistribute) and as
"deleted" (when it is only in google'able places) and have
an informal state "removed" when it is finally wiped off
the archive. Or should that be the other way round - may
be a matter of taste and anglophonic people might be able
to tell what words to pick for the better.

btw, what about two phasis when being _within_ the main
categories of the ac-archive - like "proposed" and
"stable" as we know from other standardization processes.
The "proposed" might change slightly in behaviour in
corner cases, the "stable" one may not and only get
safe bugfixes in new versions of its macro.

wdyt, cheers, guido
p.s. sorry, the "state"-attribution comes up again and
     again from my mind ;-)