diff options
| -rw-r--r-- | doc/manual.cli | 13 |
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 |