LU-7699 build: Replace version_tag.pl with LUSTRE-VERSION-GEN

[fs/lustre-release.git] / Documentation / versioning.txt

diff --git a/Documentation/versioning.txt b/Documentation/versioning.txt
new file mode 100644 (file)
index 0000000..c96965d
--- /dev/null
+++ b/Documentation/versioning.txt
@@ -0,0 +1,82 @@
+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