Re: The Policy(tm)

[Guido Draheim]

Peter Simons schrieb:
> Here is the complete policy text as it is now. (Also available on the
> web site, for those who prefer marked-up text.)
>
> As always, I'll appreciate any feedback!
>
>                     Autoconf Macro Archive Policy
>
> Introduction
>
>     The GNU Autoconf Macro Archive aims to provide a central
>     repository of useful and tested Autoconf macros for software
>     developers around the world. 

a\ We accept all the macros that go beyond base autoconf project,
possibly for being to specific or used in just some corners
of software development - the GNU Autoconf Macro Archive is the
right place to hold all of them.


>     In order to reach this goal, the
>     members of the ac-archive-maintainers mailing list collaborated to
>     define a policy, which regulates the requirements a macro must
>     fulfill in order to be accepted into the archive. Having such a
>     policy is meant to ensure a certain level of quality and
>     consistency throughout the macros distributed as part of the
>     archive. However, these requirements are not set in stone forever;
>     if you have any ideas for improving the archive's policy, please
>     let us know!
>
> General Policy
>
>      1. All macros accepted into the archive must be licensed under
>         the terms of the GNU General Public License.

actually, all macros must be GPL-compatible since they will be wrapped up
with others in aclocal.m4 and configure output scripts. Specifically,
these are done with automatic tools and an (old-)bsd advertiser
clause could not be heeded with that automatics. ((new-)bsd according
to gnu.org-speak is okay however - it is GPL-compatible).

>      2. No two macros in the archive should perform the same test. We
>         do not wish to confuse (potentially inexperienced) Autoconf
>         users by providing two competing macros for the same purpose.
>         Instead, the existing macro's functionality should be enhanced
>         to fulfill the requirements, or the existing macro should be
>         replaced completely by a new submission.

There are a lot of places where two macros target the same test-area
but they handle the result differently - like adding a default-source,
adding a -Define somewhere, some introducing new --enabled extensions.
However, (a) two macros should be named distinctivly enough to show
these difference (b) the name should hint about the actual result (e.g.
AX_HAVE and AX_WITH to differentiate -Definers and --enable'rs) and
(c) we try hard to put up crosslinks between `variants` of the same
functionality area and ask developers to accept that into the doc part
of their macro submissions.

>      3. Every macro will be sorted into one of the following
>         categories:

even that it would be empty at the moment - a `fortran` category
would be good as well ;-) - there are some people who do really
care and use some autoconf tricks to get away with the different
contemporary fortran compilers.

> Macro Submission Procedure
>
>     Every macro submission has to go through the following steps in
>     order to be accepted into the archive:
>
>      1. The archive maintainers verify that the submission fulfills
>         the very basic requirements concerning formatting, naming
>         policy, etc. If it does not, one of them gets back to the
>         author to discuss the necessary changes.
>
>      2. The submission is added to the Candidate" category, which is
>         not part of the release archive, but available only on the web
>         page.
>
>      3. An announcement of the new arrival is posted an the web site,
>         to the not-yet-determined mailing list, and -- possibly --
>         posted on the Autoconf mailing list as well. (If they don't
>         mind.)
>
>         Everybody is invited to comment on the macros quality --
>         positively or negatively. Every comment must clearly state
>         either of:
>
>           + I vote for the inclusion of the macro.
>
>           + I vote against the inclusion of the macro.
>
>         Votes without any reasoning (even a trivial one) don't count.
>
>      4. After a two week period, the votes are counted and the macro
>         is accepted or not (simple majority suffices). The mere fact
>         that the macro has been submitted by the author is counted as
>         an implicit vote for inclusion into the archive. So if no-one
>         speaks up, the macro is accepted.

Hmmm, I would like to weaken this policy a bit - some macros are good
enough to get through a shortcut-path. Perhaps this: a RFC request on
the autoconf main mailing list plus three days will be accepted as a
shortcut-path to put it into the main trunk of the ac-archive. The
two-weeks apply for the ac-archive' specific mailinglist.

> Macro Naming Convention
>
>      1. Macro names must begin with the prefix AX_, what is short-hand
>         for "Autoconf Extension".

s/must/should/ (i.e. good reason must be given when picking another).

>      2. Macro names must be spelled in all upper-case and consist only
>         of the letters of the (US-ASCII) alphabet, digits, and
>         underscores.

s/must/should/ (i.e. good r....)

>      3. The use of a second "prefix" after the initial AX_, such as
>         the initials of the author etc., is not necessary, because the
>         archive maintainers will ensure unique macro names throughout
>         the archive.

ack. a\ the second word should tell of the test-kind (CHECK/HAVE/etc)
to be easily recognizable. A variation token should instead be
appended to the end of the macro if such is ever needed at all since
archive maintainer will try hard to get a streamlined name anyway
without initials of an author etc.

>      4. Macros should try to follow the naming scheme of the macros
>         distributed with the Autoconf package. For example, a macro
>         that finds an installed program on the system would be called
>         AX_PROG_PROGRAM-NAME. A macro that tests whether the type
>         foo_t is defined in the system headers, should be called
>         AX_TYPE_FOO_T, and so on.

ooops, duplicating my notes above ;-) ... ahmm, swap 3./4. in the text?

> Updating Macros
>
>      1. Updates to macros in the archive must not change the principal
>         interface to the user. What constitutes an "interface change"
>         and what does not is hard to describe for all possible cases,
>         but here are a few guidelines:
>
>          a. The order of the expected parameters must not change.
>
>          b. Newly added parameters must be optional.
>
>          c. The variables defined by the macro to return its results
>             must not be renamed or change semantics.

           d. Minus occasions where (a) thru (c) constitutes formal
              interface parts being never used for being not useful
              or permanently broken up to the update point anway.
>         Generally, the idea is that a perfectly working configure
>         script must not break if the author uses the new version of
>         the macro.
>
>      2. If a macro does break backwards compatibility -- what may be
>         technically warranted sometimes --, it must be submitted to
>         the archive under a new name. With the acceptance of the new
>         macro into the archive, the old version will be marked as
>         obsolete.

s/marked/generally marked/

>      3. When the changes to a macro are too substantial for the
>         maintainers to judge them, the new version may have to go
>         through the submission procedure in order to be accepted.
>
> Obsoletion of Macros
>
>     A macro distributed as part of the archive may become obsolete for
>     the following reasons:
>
>      1. It has been included into the official Autoconf distribution.
>
>      2. It has been replaced by a new, technically superior macro.
>
>      3. It has severe known deficits.
>
>     An obsoleted macro will be moved into the "Obsolete" category and
>     will remain there for a 12 months period. Furthermore, the macro's
>     description on the web page and in the source code will state that
>     it is obsolete, thus allowing tools like acinclue and aclocal to
>     warn the user about using it.
a\ The obsoleted macros will be still shipped for some time, therefore
>     The names of obsolete macros are still reserved within the archive
>     and may not be used by new submissions. When the 12 month
>     transition period is over, the macro will be removed from the
>     archive. At this point, its name becomes free for re-use by new
>     submissions.


> Releases

s/ On the 1st day / Usually at the end of /
  (people interpret month release dates as `including` that month - see
   software industry habits of `0803` schedule being `shipment at end of
   august` - internally the freeze is earlier due to CD-making and packaging).
   Furthermore, I vote against a monthly update since administrators
   will not usually follow monthly updates - perhaps make it at two-month
   intervals if needs to be regular.

>     On the 1st day of each month, an official release of the archive's
>     contents is published as a tar.gz archive and as an RPM archive.
>     These archives will be named according to the scheme:
>
>         autoconf-archive-YYYY-MM.tar.gz
>
>     Where the YYYY stands for the year of the release and the MM
>     stands for the month of the release. Thus, the archive released an
>     Sep 1st, 2003 will have the file name:
>
>         autoconf-archive-2003-09.tar.gz
>
>     The most current release will be available under the name:
>
>         autoconf-archive.tar.gz
>
> Transition Plan
>
>     When the Macro Archive was founded, the policy for accepting
>     macros was, basically, "we accept anything unless it is glaringly
>     obvious that it's junk". This poses a problem now, because the
>     archive does contain dozens of macros already, and none of them
>     conforms to the policy outlined above. In order to remedy this
>     situation, the following plan for transition has been made.
>
>      1. All existing macros will be marked as obsolete. Since they
>         have been around for so long, they will expire in 18 months,
>         instead of the usual 12 months.