Latest Policy

[Peter Simons]

Appended below (and available at
http://www.gnu.org/software/ac-archive/policy.html), is the latest
version of the policy document. I think that this is finally getting
somewhere and I would like to finish the ASAP so that we can finally
begin with the implementation of these changes.

If there is anything in there that you think should be re-considered,
please speak up!

Peter


                    Autoconf Macro Archive Policy

Table of Contents

1. Introduction
2. General Requirements
3. Macro Naming Convention
4. Macro Submission Procedure
5. Updating Macros
6. Obsoletion of Macros
7. Overlapping Functionality
8. Releases
A. Transition Plan

1. Introduction

The GNU Autoconf Macro Archive aims to provide a central repository of
useful and tested Autoconf macros for software developers around the
world. 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!

2. General Requirements

  * All macros accepted into the archive must be licensed as free
    software. We accept any GPL-compatible license, as listed on the
    gnu.org license page page. For consistency, we recommend to use
    the same license as the Autoconf tool suite itself: the GNU
    General Public License with this special GPL Exception.

  * 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.

  * Every macro will be sorted into one of the following categories:

    C++ Language Support
        Testing capabilities of the C++ compiler.

    C Language Support
        Testing capabilities of the C compiler.

    Cross-Compilation
        Useful tests in a cross-compilation environment.

    Java Language Support
        Tests related to Java development.

    Installed Packages
        Finding 3rd-party software that may be installed on the
        machine.

    Miscellaneous
        Everything that didn't fit into any other category.

    System Headers and Libraries
        Testing properties of the system's header files and libraries.

    System Utilities
        Finding system utilities and properties of them.

    Build Infrastructure
        Useful tools that extend Autoconf or build infrastructure.

    Miscellaneous
        Everything that does not fit into any other category.

    Obsolete
        Obsolete Macros that will expire soon.

    Candidates
        This section will contain macros that are currently undergoing
        the submission procedure in order to be accepted into the
        archive. This category is available on the web page only; its
        contents is not distributed as part of the release archive.

3. Macro Naming Convention

  * Macro names must begin with the prefix AX_, what is short-hand for
    "Autoconf Extension".

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

  * 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.

  * 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.

4. 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.

5. Updating Macros

  * 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:

      + The order of the expected parameters must not change.

      + Newly added parameters must be optional.

      + The variables defined by the macro to return its results must not be
        renamed or change semantics.

    Generally, the idea is that a perfectly working configure script
    must not break if the author uses the new version of the macro.

  * 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.

  * 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.

6. Obsoletion of Macros

A macro distributed as part of the archive may become obsolete for the
following reasons:

  * It has been included into the official Autoconf distribution.

  * It has been replaced by a new, technically superior macro.

  * 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.

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.

7. Overlapping Functionality

As stated before, no two macros in the archive should perform the same
test. In case, a submission comes in, which duplicates functionality
of an existing macro or of a macro that is currently going through the
submission procedure, the authors of the respective macros are
informed, in the hope that they will be able to determine the best
course of action:

  * They merge the functionality and submit an update to the existing
    macro.

  * They agree to replace the existing macro with the new submission,
    thereby obsoleting the original one.

In the unfortunate case of the two authors being unable to agree, the
submission procedure continues as follows.

Competing submissions

 1. The review period of all competing macros will start from the
    scratch.

 2. In a combined announcement for all competing macros, it will be
    clearly stated that only one of the competing macros will be
    accepted into the archive.

 3. Reviewers are allowed to vote in favor (or against) all competing
    macros; the votes are not restricted to one macro.

 4. Of all macros with a majority of "accept" votes, the one with the
    greatest number of "accept" votes is accepted into the archive.
    All other competing macros are refused.

 5. In case of a draw, the archive maintainers will do whatever they
    think is best. :-)

Submission competing with existing macro

 1. The review period of the submitted macro will start from the
    scratch.

 2. In the announcement, it will be clearly stated that this macro
    will -- when accepted -- replace the macro currently in the
    archive.

 3. If the macro receives a majority of "accept" votes, it will
    replace the macro currently in the archive, which is obsoleted.

8. Releases

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

A. 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.

 2. The archive maintainers will evaluate the current macros to
    determine the necessary changes to them in order to comply to the
    new policy. Then we contact the respective author (where
    possible), advice him of our little project, and beg him to please
    make those changes.

 3. If the author refuses or cannot be reached, we make those changes
    ourselves ... Or we don't, and let the macro expire.

 4. If we feel that a macro needs more substantial changes in order to
    be re-accepted, we go through the formal submission procedure.
    Otherwise we just put the "fixed" version into the official
    section.