aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2017-04-28 14:37:27 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2017-04-28 14:37:27 +0200
commit0fab09e0a93dcb52e5e010512ec96d70561443aa (patch)
treef91e8ef7ef3f5c0c3484281b40432e479e079c0a
parent5b3f44dea04c0a6184fe54270562471117347abe (diff)
Improve documentation
-rw-r--r--doc/manual.cli13
1 files changed, 12 insertions, 1 deletions
diff --git a/doc/manual.cli b/doc/manual.cli
index f0a879f..f23c0f3 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -368,7 +368,8 @@ 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.
+and manages all this information automatically (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
@@ -486,6 +487,16 @@ 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.
+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
+commits with the same date (but not the same commit id and thus snapshot
+id). We also need all the committers to have a reasonably accurate
+clock. Note, however, that in case of a commit date clash/ordering issue, we
+still end up with distinct versions (because of the commit id) \- they are
+just not ordered correctly. As a result, we feel that the risks are justified
+when the only alternative is manual version management (which is always an
+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