Lustre versioning
=================

This document describes versioning of source and binaries for Lustre.

Versions
========

The Lustre version is generated by the LUSTRE-VERSION-GEN script at the
top level of the lustre source tree.  The script prints the version to
stdout and also updates the file at the top of the source tree named
LUSTRE-VERSION-FILE to contain the current version (if the file does not
already exist, or if it contains an out-of-date version).

LUSTRE-VERISON-GEN is called when the autotools are initialized,
either when autogen.sh is run or when autoreconf runs.  The stdout
of the script is used as the version option of AC_INIT in configure.ac.
This ensures that the AC_PACKAGE_VERSION m4 macro, the PACKAGE_VERSION
output variable, and the PACKAGE_VERSION preprocessor symbol are all
correctly set to the current version.  Likewise AC_PACKAGE_STRING and
PACKAGE_STRING will contain the current version.

If the lustre tree is in a git working directory, LUSTRE-VERSION-GEN
uses "git --describe" to generate the version number.  If the tree is
not in a git working directory but a LUSTRE-VERSION-FILE file exists
(such as in the tarball created by "make dist"), the script falls back
to using the value in the file.  Finally, if it is not a git working
directory and the LUSTRE-VERSION-FILE also does not exist (such as when
the source tree is retrieved with "git archive --remote") LUSTRE-VERSION-GEN
will fall back to using its own internal DEFAULT_VERSION variable.

Tagging Guidelines - General
============================

It is best practice to edit the DEFAULT_VERSION in LUSTRE-VERSION-GEN
before creating a tag of the same name.  Public community versions
should have the form "1.1.1" or "1.1.1.1".

Tagging Guildines - Third Party
===============================

Third parties (e.g. vendors, labs, universities) that wish to tag their
own releases should append a version that unamiguously identifies the
release for their organization.  This is done by adding an underscore,
and then a unique version to the tag.

For instance, lets consider a vendor named Acme.  They are releasing a
their second patched version of Lustre 2.8.0 to their customers.  They
would set the version to something like the following:

  2.8.0_2.acme

The third party subversion string can contain alphanumerics, underscores,
and periods.

Strictly speaking, if one is certain that the third party release code
will only be built from inside a git working directory, only a git tag
need be made.  In other words, creating a git commit to update the
DEFAULT_VERSION in LUSTRE-VERSION-GEN is a not always necessary.
LUSTRE-VERSION-GEN can retrieve the version solely using git, from the
git tag and git describe information.

Releases
========

Major releases should get a 3-digit version x.y.0, and if a maintenance
release is needed it will increment the 3rd digit.  During development,
versions start at x.y.50 and increment toward the x.(y+1).0 release.

Usage:
------

New numbers are used as follows:

1. major:
 - increased when major new functionality becomes available
2. minor:
 - for each new release with new functionality
3. patch:
 - for a stable maintenance release or development snapshot
4. fix:
 - minor fix release