[PATCH 01/10] 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.  This
series of patches introduces a way for CLI callers to request a
specific schema 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 schema
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.
---
 Makefile.local   |    1 +
 notmuch-client.h |   46 ++++++++++++++++++++++++++++++++++++++++++++++
 notmuch.c        |    3 +++
 schema.c         |   46 ++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 96 insertions(+)
 create mode 100644 schema.c

diff --git a/Makefile.local b/Makefile.local
index 2b91946..bfed50e 100644
--- a/Makefile.local
+++ b/Makefile.local
@@ -274,6 +274,7 @@ notmuch_client_srcs =		\
 	query-string.c		\
 	mime-node.c		\
 	crypto.c		\
+	schema.c		\
 
 notmuch_client_modules = $(notmuch_client_srcs:.c=.o)
 
diff --git a/notmuch-client.h b/notmuch-client.h
index ae9344b..14e7363 100644
--- a/notmuch-client.h
+++ b/notmuch-client.h
@@ -117,6 +117,52 @@ chomp_newline (char *str)
 	str[strlen(str)-1] = '\0';
 }
 
+/* Exit status code indicating the requested schema version is too old
+ * (support for that version has been dropped).  CLI code should use
+ * notmuch_exit_if_unsupported_schema rather than directly exiting
+ * with this code.
+ */
+#define NOTMUCH_EXIT_SCHEMA_TOO_OLD 20
+/* Exit status code indicating the requested schema version is newer
+ * than the version supported by the CLI.  CLI code should use
+ * notmuch_exit_if_unsupported_schema rather than directly exiting
+ * with this code.
+ */
+#define NOTMUCH_EXIT_SCHEMA_TOO_NEW 21
+
+/* The version number of the current structured output schema.
+ * Requests for schema 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 map fields can be added
+ * without increasing this.  Note that different notmuch commands may
+ * support different backwards-compatible version numbers, but the
+ * "current" version is consistent across all parts of the schema.
+ */
+#define NOTMUCH_SCHEMA_CUR 1
+
+/* The schema version requested by the caller on the command line.  If
+ * no schema version is requested, this should be set to
+ * NOTMUCH_SCHEMA_CUR.  This is global---rather than per
+ * command---because commands can share structured output code.
+ */
+extern int notmuch_schema_version;
+
+/* Commands that support structured output should support the
+ * following argument
+ *  { NOTMUCH_OPT_INT, &notmuch_schema_version, "use-schema", 0, 0 }
+ * and should invoke notmuch_exit_if_unsupported_schema to check
+ * against the per-command minimum supported schema version and the
+ * global maximum supported schema version.  If notmuch_schema_version
+ * is outside the supported range, this will print a detailed
+ * diagnostic message for the user and exit with
+ * NOTMUCH_EXIT_SCHEMA_TOO_{OLD,NEW} to inform the invoking program of
+ * the problem.
+ */
+void
+notmuch_exit_if_unsupported_schema (const char *command,
+				    int min_schema_version);
+
 notmuch_crypto_context_t *
 notmuch_crypto_get_context (notmuch_crypto_t *crypto, const char *protocol);
 
diff --git a/notmuch.c b/notmuch.c
index 477a09c..ed860f2 100644
--- a/notmuch.c
+++ b/notmuch.c
@@ -242,6 +242,9 @@ main (int argc, char *argv[])
     g_mime_init (0);
     g_type_init ();
 
+    /* Globally default to the current schema version. */
+    notmuch_schema_version = NOTMUCH_SCHEMA_CUR;
+
     if (argc == 1)
 	return notmuch (local);
 
diff --git a/schema.c b/schema.c
new file mode 100644
index 0000000..4b6c4fa
--- /dev/null
+++ b/schema.c
@@ -0,0 +1,46 @@
+/* notmuch - Not much of an email program, (just index and search)
+ *
+ * This file is part of notmuch.
+ *
+ * Copyright © 2012 Austin Clements
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see http://www.gnu.org/licenses/ .
+ *
+ * Author: Austin Clements <aclements at csail.mit.edu>
+ */
+
+#include "notmuch-client.h"
+
+int notmuch_schema_version;
+
+void
+notmuch_exit_if_unsupported_schema (const char *command,
+				    int min_schema_version)
+{
+    if (notmuch_schema_version > NOTMUCH_SCHEMA_CUR) {
+	fprintf (stderr, "\
+A caller requested a newer output format (schema version %d) than\n\
+supported by the notmuch CLI (which supports up to version %d).  You\n\
+may need to upgrade your notmuch CLI.\n",
+		 notmuch_schema_version, NOTMUCH_SCHEMA_CUR);
+	exit (NOTMUCH_EXIT_SCHEMA_TOO_NEW);
+    } else if (notmuch_schema_version < min_schema_version) {
+	fprintf (stderr, "\
+A caller requested an older output format (schema version %d) than\n\
+supported by the %s command of the notmuch CLI (which requires at\n\
+least version %d).  You may need to upgrade your notmuch front-end.\n",
+		 notmuch_schema_version, command, min_schema_version);
+	exit (NOTMUCH_EXIT_SCHEMA_TOO_OLD);
+    }
+}
-- 
1.7.10.4