Merge pull request containers#239 from alexlarsson/release

Document versioning and bump version for release.

configure.ac

@@ -1,5 +1,5 @@
 AC_PREREQ([2.69])
-AC_INIT([composefs], [1.0.2], [[email protected]])
+AC_INIT([composefs], [1.0.3], [[email protected]])
 AC_CONFIG_SRCDIR([tools/mkcomposefs.c])
 AC_CONFIG_HEADERS([config.h])
 AC_SYS_LARGEFILE
@@ -21,8 +21,8 @@ AC_SYS_LARGEFILE
 # (And never do that lightly)
 
 m4_define([LIBCOMPOSEFS_VERSION_MAJOR], [1])
-m4_define([LIBCOMPOSEFS_VERSION_MINOR], [0])
-m4_define([LIBCOMPOSEFS_VERSION_MICRO], [1])
+m4_define([LIBCOMPOSEFS_VERSION_MINOR], [1])
+m4_define([LIBCOMPOSEFS_VERSION_MICRO], [0])
 
 LT_PREREQ([2.2.6])
 LT_INIT()

libcomposefs/lcfs-writer.h

@@ -51,7 +51,7 @@ enum lcfs_flags_t {
 #define LCFS_VERSION_MAX 1
 /* Version history:
  * 0 - Initial version
- * 1 - Mark xwhitouts using the new opaque=x format as needed by Linux 6.8
+ * 1 - Mark xwhitouts using the opaque=x format (1.0.3)
  */
 
 /* Default value used by tooling, update with care */

man/mkcomposefs.md

@@ -60,6 +60,43 @@ will be a mountable composefs image.
 :   The source is a file in the **composefs-dump(5)** format. If
     the specified file is "-", the data is read from stdin.
 
+**\-\-version**
+:   The base version to use for the image format.
+
+**\-\-max-version**
+:   If this specifies a version higher than \-\-version, then the
+    actual image format version used will be adjusted upwards if that
+    is beneficial for the image, up to the max version.
+
+# FORMAT VERSIONING
+
+Composefs images are binary reproduceable, meaning that for a given
+input the result is always the same, giving the same digest of the
+image. This is important as the digest is used to validate the image,
+even if the image was re-created rather than transferred as
+is. However, sometimes the format needs to be changed, such as for
+example when a new type of file is introduced or a bug is fixed. This
+is handled by introducing a format version.
+
+Specifying the version is done with two options, the base version
+(\-\-version) and the max version (\-\-max-version). When building an
+image, mkcomposefs tries to keep the image format as low as possible,
+but if some particular requested feature is not available with the
+base feature, but is accessible in the max version then the version
+used will be increased. This allows us to introduce new features and
+fix bugs in a later version and migrate to that using max versions,
+but still keeping the digests identical for unaffected images.
+
+If you need 100% binary reproducibility over time, specify the same
+version and a max version each time.
+
+Format version history:
+
+- 0 - Initial version
+- 1 - Supports overlay whiteout files in the image (added in 1.0.3)
+
+The default if no version arguments are specified is version 0 and max
+version 1.
 
 # SEE ALSO
 **composefs-info(1)**, **mount.composefs(1)**, **composefs-dump(5)**

tools/mkcomposefs.c

@@ -911,8 +911,9 @@ int main(int argc, char **argv)
 	int opt;
 	FILE *out_file;
 	char *failed_path;
-	long min_version = LCFS_DEFAULT_VERSION_MIN;
-	long max_version = LCFS_DEFAULT_VERSION_MAX;
+	bool version_set = false;
+	long min_version = 0;
+	long max_version = 0;
 	char *end;
 
 	/* We always compute the digest and reference by digest */
@@ -945,13 +946,15 @@ int main(int argc, char **argv)
 			from_file = true;
 			break;
 		case OPT_MIN_VERSION:
+			version_set = true;
 			min_version = strtol(optarg, &end, 10);
 			if (*optarg == 0 || *end != 0) {
 				fprintf(stderr, "Invalid min version %s\n", optarg);
 				exit(EXIT_FAILURE);
 			}
 			break;
 		case OPT_MAX_VERSION:
+			version_set = true;
 			max_version = strtol(optarg, &end, 10);
 			if (*optarg == 0 || *end != 0) {
 				fprintf(stderr, "Invalid max version %s\n", optarg);
@@ -967,6 +970,11 @@ int main(int argc, char **argv)
 		}
 	}
 
+	if (!version_set) {
+		min_version = LCFS_DEFAULT_VERSION_MIN;
+		max_version = LCFS_DEFAULT_VERSION_MAX;
+	}
+
 	argv += optind;
 	argc -= optind;