Policy: Versioning Macros In The Archive

[Peter Simons]

Hi,

as you may have noticed, the contents of the @version tag in
the archive has changed a bit. It's no longer free text, but
it's an ISO8601 formatted date, as in:

  @version 2005-01-24

This date is supposed to signify the day of the last change
to the _macro_. For the vast majority of entries we have
right now, that is the day of the original submission.

 * The version MUST be bumped to "today" when the m4 source
   code is modified.

 * It SHOULD NOT be bumped when only the documentation is
   updated. You MAY bump it, though, when those changes have
   been extensive.

 * The version of an entry MUST be bumped when it becomes
   obsolete. The date then essentially signifies the day the
   macro became obsolete, so we can use that information to
   omit it from the index after 3 months; and to discard it
   from the archive after 1 year.

For convenience:

The original submitter can still use free text as long as it
does contain an ISO-like date string. The "axlint" tool will
pick that date out and canonize the @version tag. Thus, it
is perfectly okay to submit a macro with a version tag like
this one:

  @version $Id: foo.m4,v 1.2 2004/02/15 10:09:31 bar Exp $

It will come out:

  @version 2004-02-15

I do have a small script at <http://cryp.to/redate> that
helps with updating version information in files.

In the future, the build system might be able to help
automating these tasks. The "genarchive" tool could dump a
branch of the macros which contained only the m4 source,
then changes in these parts could be detected automatically
and a "redate" could be run on the corresponding original
file (in a checked-out repository), so that the maintainers
notice the change when executing "cvs diff".

That's just a wild idea, though.

Nothing is set in stone. If anyone has better ideas, let's
hear them!

Peter