[PATCH 1/7] cli: Framework for structured output versioning

[Austin Clements]

Currently there is a period of pain whenever we make
backward-incompatible changes to the structured output format, which
discourages not only backward-incompatible improvements to the format,
but also backwards-compatible additions that may not be "perfect".  In
the end, these problems limit experimentation and innovation.

This series of patches introduces a way for CLI callers to request a
specific format version on the command line and to determine if the
CLI does not supported the requested version (and perhaps present a
useful diagnostic to the user).  Since the caller requests a format
version, it's also possible for the CLI to support multiple
incompatible versions simultaneously, unlike the alternate approach of
including version information in the output.

This patch lays the groundwork by introducing a versioning convention,
standard exit codes, and a utility function to check the requested
version and produce standardized diagnostic messages and exit
statuses.
---
 devel/schemata   |    2 ++
 notmuch-client.h |   45 +++++++++++++++++++++++++++++++++++++++++++++
 notmuch.c        |   32 ++++++++++++++++++++++++++++++++
 3 files changed, 79 insertions(+)

diff --git a/devel/schemata b/devel/schemata
index d1ab983..292f287 100644
--- a/devel/schemata
+++ b/devel/schemata
@@ -14,6 +14,8 @@ are interleaved. Keys are printed as keywords (symbols preceded by a
 colon), e.g. (:id "123" :time 54321 :from "foobar"). Null is printed as
 nil, true as t and false as nil.
 
+This is version 1 of the structured output format.
+
 Common non-terminals
 --------------------
 
diff --git a/notmuch-client.h b/notmuch-client.h
index 1c336dc..d7b352e 100644
--- a/notmuch-client.h
+++ b/notmuch-client.h
@@ -117,6 +117,51 @@ chomp_newline (char *str)
 	str[strlen(str)-1] = '\0';
 }
 
+/* Exit status code indicating the requested format version is too old
+ * (support for that version has been dropped).  CLI code should use
+ * notmuch_exit_if_unsupported_format rather than directly exiting
+ * with this code.
+ */
+#define NOTMUCH_EXIT_FORMAT_TOO_OLD 20
+/* Exit status code indicating the requested format version is newer
+ * than the version supported by the CLI.  CLI code should use
+ * notmuch_exit_if_unsupported_format rather than directly exiting
+ * with this code.
+ */
+#define NOTMUCH_EXIT_FORMAT_TOO_NEW 21
+
+/* The current structured output format version.  Requests for format
+ * versions above this will return an error.  Backwards-incompatible
+ * changes such as removing map fields, changing the meaning of map
+ * fields, or changing the meanings of list elements should increase
+ * this.  New (required) map fields can be added without increasing
+ * this.
+ */
+#define NOTMUCH_FORMAT_CUR 1
+/* The minimum supported structured output format version.  Requests
+ * for format versions below this will return an error. */
+#define NOTMUCH_FORMAT_MIN 1
+
+/* The output format version requested by the caller on the command
+ * line.  If no format version is requested, this will be set to
+ * NOTMUCH_FORMAT_CUR.  Even though the command-line option is
+ * per-command, this is global because commands can share structured
+ * output code.
+ */
+extern int notmuch_format_version;
+
+/* Commands that support structured output should support the
+ * following argument
+ *  { NOTMUCH_OPT_INT, &notmuch_format_version, "format-version", 0, 0 }
+ * and should invoke notmuch_exit_if_unsupported_format to check the
+ * requested version.  If notmuch_format_version is outside the
+ * supported range, this will print a detailed diagnostic message for
+ * the user and exit with NOTMUCH_EXIT_FORMAT_TOO_{OLD,NEW} to inform
+ * the invoking program of the problem.
+ */
+void
+notmuch_exit_if_unsupported_format (void);
+
 notmuch_crypto_context_t *
 notmuch_crypto_get_context (notmuch_crypto_t *crypto, const char *protocol);
 
diff --git a/notmuch.c b/notmuch.c
index 4ff66e3..9516dfb 100644
--- a/notmuch.c
+++ b/notmuch.c
@@ -82,6 +82,8 @@ static command_t commands[] = {
       "This message, or more detailed help for the named command." }
 };
 
+int notmuch_format_version;
+
 static void
 usage (FILE *out)
 {
@@ -109,6 +111,33 @@ usage (FILE *out)
     "and \"notmuch help search-terms\" for the common search-terms syntax.\n\n");
 }
 
+void
+notmuch_exit_if_unsupported_format (void)
+{
+    if (notmuch_format_version > NOTMUCH_FORMAT_CUR) {
+	fprintf (stderr, "\
+A caller requested output format version %d, but the installed notmuch\n\
+CLI only supports up to format version %d.  You may need to upgrade your\n\
+notmuch CLI.\n",
+		 notmuch_format_version, NOTMUCH_FORMAT_CUR);
+	exit (NOTMUCH_EXIT_FORMAT_TOO_NEW);
+    } else if (notmuch_format_version < NOTMUCH_FORMAT_MIN) {
+	fprintf (stderr, "\
+A caller requested output format version %d, which is no longer supported\n\
+by the notmuch CLI (it requires at least version %d).  You may need to\n\
+upgrade your notmuch front-end.\n",
+		 notmuch_format_version, NOTMUCH_FORMAT_MIN);
+	exit (NOTMUCH_EXIT_FORMAT_TOO_OLD);
+    } else if (notmuch_format_version != NOTMUCH_FORMAT_CUR) {
+	/* Warn about old version requests so compatibility issues are
+	 * less likely when we drop support for a deprecated format
+	 * versions. */
+	fprintf (stderr, "\
+A caller requested deprecated output format version %d, which may not\n\
+be supported in the future.\n", notmuch_format_version);
+    }
+}
+
 static void
 exec_man (const char *page)
 {
@@ -242,6 +271,9 @@ main (int argc, char *argv[])
     g_mime_init (0);
     g_type_init ();
 
+    /* Globally default to the current output format version. */
+    notmuch_format_version = NOTMUCH_FORMAT_CUR;
+
     if (argc == 1)
 	return notmuch (local);
 
-- 
1.7.10.4