The Policy(tm)

[Peter Simons]

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

     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.

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

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.

Macro Naming Convention

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

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

     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.

     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.

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.

        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.

     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.

    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

    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.

     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.