Documentation/versioning.txt

   1 Lustre versioning
   2 =================
   3
   4 This document describes versioning of source and binaries for Lustre.
   5
   6 Versions
   7 ========
   8
   9 The Lustre version is generated by the LUSTRE-VERSION-GEN script at the
  10 top level of the lustre source tree.  The script prints the version to
  11 stdout and also updates the file at the top of the source tree named
  12 LUSTRE-VERSION-FILE to contain the current version (if the file does not
  13 already exist, or if it contains an out-of-date version).
  14
  15 LUSTRE-VERISON-GEN is called when the autotools are initialized,
  16 either when autogen.sh is run or when autoreconf runs.  The stdout
  17 of the script is used as the version option of AC_INIT in configure.ac.
  18 This ensures that the AC_PACKAGE_VERSION m4 macro, the PACKAGE_VERSION
  19 output variable, and the PACKAGE_VERSION preprocessor symbol are all
  20 correctly set to the current version.  Likewise AC_PACKAGE_STRING and
  21 PACKAGE_STRING will contain the current version.
  22
  23 If the lustre tree is in a git working directory, LUSTRE-VERSION-GEN
  24 uses "git --describe" to generate the version number.  If the tree is
  25 not in a git working directory but a LUSTRE-VERSION-FILE file exists
  26 (such as in the tarball created by "make dist"), the script falls back
  27 to using the value in the file.  Finally, if it is not a git working
  28 directory and the LUSTRE-VERSION-FILE also does not exist (such as when
  29 the source tree is retrieved with "git archive --remote") LUSTRE-VERSION-GEN
  30 will fall back to using its own internal DEFAULT_VERSION variable.
  31
  32 Tagging Guidelines - General
  33 ============================
  34
  35 It is best practice to edit the DEFAULT_VERSION in LUSTRE-VERSION-GEN
  36 before creating a tag of the same name.  Public community versions
  37 should have the form "1.1.1" or "1.1.1.1".
  38
  39 Tagging Guildines - Third Party
  40 ===============================
  41
  42 Third parties (e.g. vendors, labs, universities) that wish to tag their
  43 own releases should append a version that unamiguously identifies the
  44 release for their organization.  This is done by adding an underscore,
  45 and then a unique version to the tag.
  46
  47 For instance, lets consider a vendor named Acme.  They are releasing a
  48 their second patched version of Lustre 2.8.0 to their customers.  They
  49 would set the version to something like the following:
  50
  51   2.8.0_2.acme
  52
  53 The third party subversion string can contain alphanumerics, underscores,
  54 and periods.
  55
  56 Strictly speaking, if one is certain that the third party release code
  57 will only be built from inside a git working directory, only a git tag
  58 need be made.  In other words, creating a git commit to update the
  59 DEFAULT_VERSION in LUSTRE-VERSION-GEN is a not always necessary.
  60 LUSTRE-VERSION-GEN can retrieve the version solely using git, from the
  61 git tag and git describe information.
  62
  63 Releases
  64 ========
  65
  66 Major releases should get a 3-digit version x.y.0, and if a maintenance
  67 release is needed it will increment the 3rd digit.  During development,
  68 versions start at x.y.50 and increment toward the x.(y+1).0 release.
  69
  70 Usage:
  71 ------
  72
  73 New numbers are used as follows:
  74
  75 1. major:
  76  - increased when major new functionality becomes available
  77 2. minor:
  78  - for each new release with new functionality
  79 3. patch:
  80  - for a stable maintenance release or development snapshot
  81 4. fix:
  82  - minor fix release