aboutsummaryrefslogtreecommitdiff
path: root/doc/manual.cli
diff options
context:
space:
mode:
Diffstat (limited to 'doc/manual.cli')
-rw-r--r--doc/manual.cli52
1 files changed, 31 insertions, 21 deletions
diff --git a/doc/manual.cli b/doc/manual.cli
index 6dd7002..f10e54f 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -343,8 +343,9 @@ increment \i{patch} when making binary-compatible changes, \i{minor} when
making source-compatible changes, and \i{major} when making breaking changes.
While the binary compatibility must be set in stone, the source compatibility
rules can sometimes be bent. For example, you may decide to make a breaking
-change in a rarely used interface as part of a minor release. Note also that
-in the context of C++ deciding whether a change is binary-compatible is a
+change in a rarely used interface as part of a minor release (though this is
+probably still a bad idea if your library is widely depended upon). Note also
+that in the context of C++ deciding whether a change is binary-compatible is a
non-trivial task. There are resources that list the rules but no automated
tooling yet. If unsure, increment \i{minor}.
@@ -379,10 +380,11 @@ worse, from the final release. One way to remedy this is to increment the
pre-release number before each publication. However, unless automated, this
will be burdensome and error-prone. Also, there is a real possibility of
running out of version numbers if, for example, we do continuous integration
-by testing (and therefore publishing) each commit.
+by publishing and testing each commit.
To address this, the standard versioning scheme supports \i{snapshot
-pre-releases} with the \i{prerel} component having the following form:
+pre-releases} with the \i{prerel} component having the following extended
+form:
\
(a|b).<num>.<snapsn>[.<snapid>]
@@ -391,13 +393,13 @@ pre-releases} with the \i{prerel} component having the following form:
For example:
\
-1.2.3-a.1.1422564055.340c0a26a5efed1f
+1.2.3-a.1.20180319215815.26efe301f4a7
\
In essence, a snapshot pre-release is after the previous final release but
before the next (\c{a.1} and, perhaps, \c{a.2} in the above example) and
is uniquely identified by the snapshot sequence number (\i{snapsn}) and
-snapshot id (\i{snapid}).
+optional snapshot id (\i{snapid}).
The \i{num} component has the same semantics as in the final pre-releases
except that it can be \c{0}. The \i{snapsn} component should be either the
@@ -408,12 +410,12 @@ uniquely identifies the snapshot. It is not required for version comparison
(\i{snapsn} should be sufficient) and is included for reference. It must not
be longer than 16 characters.
-Where do the snapshot sn and id come from? Normally from the version control
-system. For example, for \c{git}, \i{snapsn} is the commit date (as UNIX
-timestamp in the UTC timezone) and \i{snapid} is a 16-character abbreviated
-commit id. As discussed below, the \c{build2} \c{version} module extracts
-and manages all this information automatically (the use of \c{git} commit
-dates is not without limitations; see below for details).
+Where do the snapshot number and id come from? Normally from the version
+control system. For example, for \c{git}, \i{snapsn} is the commit date in the
+\i{YYYYMMDDhhmmss} form and UTC timezone and \i{snapid} is a 12-character
+abbreviated commit id. As discussed below, the \c{build2} \c{version} module
+extracts and manages all this information automatically (but the use of
+\c{git} commit dates is not without limitations; see below for details).
The special '\c{z}' \i{snapsn} value identifies the \i{latest} or
\i{uncommitted} snapshot. It is chosen to be greater than any other possible
@@ -448,7 +450,7 @@ When it comes to the version control systems, the recommended workflow is as
follows: The change to the final version should be the last commit in the
(pre-)release. It is also a good idea to tag this commit with the project
version. A commit immediately after that should change the version to a
-snapshot essentially \"opening\" the repository for development.
+snapshot, \"opening\" the repository for development.
The project version without the snapshot part can be represented as a 64-bit
decimal value comparable as integers (for example, in preprocessor
@@ -517,6 +519,7 @@ as the following build system variables (which can be used in the buildfiles):
[uint64] version.snapshot_sn # 1234567
[string] version.snapshot_id # deadbeef
[string] version.snapshot_string # 1234567.deadbeef
+[bool] version.snapshot_committed # true
[uint64] version.revision # 3
\
@@ -537,11 +540,17 @@ control system used by the project. Currently only \c{git} is supported with
the following semantics.
If the project's source directory (\c{src_root}) is clean (that is, it does
-not have any changed or untracked files), then the \c{HEAD} commit date and
-id are used as the snapshot sn and id, respectively. Otherwise, the snapshot
-is left in the \c{.z} form (which signals the latest/uncommitted
-snapshot). While we can work with such a \c{.z} snapshot locally, preparing a
-distribution of such an uncommitted snapshot is an error.
+not have any changed or untracked files), then the \c{HEAD} commit date and id
+are used as the snapshot number and id, respectively.
+
+Otherwise (that is, the project is between commits), the \c{HEAD} commit date
+is incremented by one second and is used as the snapshot number with no id.
+While we can work with such uncommitted snapshots locally, we should not
+distribute or publish them since they are indistinguishable from each other.
+
+Finally, if the project does not have \c{HEAD} (that is, the project has
+no commits yet), the special \c{19700101000000} (UNIX epoch) commit date is
+used.
The use of \c{git} commit dates for snapshot ordering has its limitations:
they have one second resolution which means it is possible to create two
@@ -555,9 +564,10 @@ option, nevertheless).
When we prepare a distribution of a snapshot, the \c{version} module
automatically adjusts the package name to include the snapshot information as
-well as patches the manifest file in the distribution with the snapshot sn and
-id (that is, replacing \c{.z} in the version value with the actual snapshot
-information). The result is a package that is specific to this commit.
+well as patches the manifest file in the distribution with the snapshot number
+and id (that is, replacing \c{.z} in the version value with the actual
+snapshot information). The result is a package that is specific to this
+commit.
Besides extracting the version information and making it available as
individual components, the \c{version} module also provide rules for