Rewrite to account for numerical sorting

Signed-off-by: Michael Bridgen <michael@weave.works>

docs/guides/flux-v1-automation-migration.md

@@ -45,7 +45,7 @@ consider. These are dealt with in detail below.
 
 Selecting an image by build time is no longer supported. This is the implicit default in Flux v1. In
 Flux v2, you will need to tag images so that they sort in the order you would like -- [see
-below](#how-to-use-timestamps-in-image-tags) for how to do this conveniently.
+below](#how-to-use-sortable-image-tags) for how to do this conveniently.
 
 #### Fields to update are explicitly marked
 
@@ -494,14 +494,14 @@ These are the prefixes supported in Flux v1, and what to use in Flux v2:
 
 | Flux v1 prefix | Meaning | Flux v2 equivalent |
 |----------------|---------|--------------------|
-| `glob:`        | Filter for tags matching the glob pattern, then select the newest by build time | [Use timestamped tags](#how-to-use-timestamps-in-image-tags) |
-| `regex:`       | Filter for tags matching the regular expression, then select the newest by build time |[Use timestamped tags](#how-to-use-timestamp-in-image-tags) |
+| `glob:`        | Filter for tags matching the glob pattern, then select the newest by build time | [Use sortable tags](#how-to-use-sortable-image-tags) |
+| `regex:`       | Filter for tags matching the regular expression, then select the newest by build time |[Use sortable tags](#how-to-use-sortable-image-tags) |
 | `semver:`      | Filter for tags that represent versions, and select the highest version in the given range | [Use semver ordering](#how-to-use-semver-image-tags) |
 
-#### How to use timestamps in image tags
+#### How to use sortable image tags
 
-To give image tags a useful ordering, you can use a timestamp as part of each image's tag, then sort
-alphabetically.
+To give image tags a useful ordering, you can use a timestamp or serial number as part of each
+image's tag, then sort either alphabetically or numerically.
 
 This is a change from Flux v1, in which the build time was fetched from each image's config, and
 didn't need to be included in the image tag. Therefore, this is likely to require a change to your

docs/guides/sortable-image-tags.md

@@ -6,36 +6,54 @@ the container config for each image, and fetching that is subject to strict rate
 registries (e.g., by [DockerHub][dockerhub-rates]).
 
 This guide explains how to construct image tags so that the most recent image has the tag that comes
-last in alphabetical order. The technique suggested is to put a timestamp or serial number in each
-image tag.
+last in alphabetical or numerical order. The technique suggested is to put a timestamp or serial
+number in each image tag.
 
 ## Formats and alternatives
 
-The important properties for sorting alphabetically are that the parts of the timestamp go from most
-significant to least (e.g., the year down to the second), and that the output is always the same
-number of characters.
+The important properties for sorting are that the parts of the timestamp go from most significant to
+least (e.g., the year down to the second). For numbers it is best to use numerical order, since this
+will work with values of different width (e.g., '12' sorts after '2').
 
-Image tags are often shown in user interfaces, so readability matters. Here are some alternatives:
+Image tags are often shown in user interfaces, so readability matters. Here is an example of a
+readable timestamp that will sort well:
 
 ```bash
-$ # seconds-since-epoch (used in the example above)
-$ date +%s
-1611840548
 $ # date and time (remember ':' is not allowed in a tag)
 $ date +%F.%H%M%S
 2021-01-28.133158
 ```
 
-Alternatively, you can use a stable serial number as part of the tag.  Some CI platforms will
-provide a build number in an environment variable, but that may not be reliable to use as a serial
-number -- check the platform documentation.
+You can use a timestamp that sorts as a number, like [Unix
+time](https://en.wikipedia.org/wiki/Unix_time):
+
+```
+$ # seconds since Jan 1 1970
+$ date +%s
+1611840548
+```
+
+Alternatively, you can use a serial number as part of the tag.  Some CI platforms will provide a
+build number in an environment variable, but that may not be reliable to use as a serial number --
+check the platform documentation.
+
+A commit count can be a reasonable stand-in for a serial number, if you build an image per commit
+and you don't rewrite the branch in question:
+
+```bash
+$ # commits in branch
+$ git --rev-list --count HEAD
+1504
+```
+
+Beware: this will not give a useful number if you have a shallow clone.
 
 ### Other things to include in the image tag
 
 It is also handy to quickly trace an image to the branch and commit of its source code. Including
 the branch also means you can filter for images from a particular branch.
 
-In sum, a useful tag format is
+A useful tag format is
 
     <branch>-<sha1>-<timestamp>
 
@@ -109,7 +127,7 @@ spec:
     pattern: '^main-[a-f0-9]+-(?P<ts>[0-9]+)'
     extract: '$ts'
   policy:
-    alphabetical:
+    numerical:
       order: asc
 ```
 
@@ -128,7 +146,7 @@ spec:
     pattern: '^.+-[a-f0-9]+-(?P<ts>[0-9]+)'
     extract: '$ts'
   policy:
-    alphabetical:
+    numerical:
       order: asc
 ```