Whamcloud - gitweb
LU-13117 libcfs: fix to match right key in cfs_get_environ()
[fs/lustre-release.git] / 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