--- /dev/null
+Return-Path: <amdragon@mit.edu>\r
+X-Original-To: notmuch@notmuchmail.org\r
+Delivered-To: notmuch@notmuchmail.org\r
+Received: from localhost (localhost [127.0.0.1])\r
+ by olra.theworths.org (Postfix) with ESMTP id 3E2F5429E39\r
+ for <notmuch@notmuchmail.org>; Sat, 1 Dec 2012 18:40:19 -0800 (PST)\r
+X-Virus-Scanned: Debian amavisd-new at olra.theworths.org\r
+X-Spam-Flag: NO\r
+X-Spam-Score: -0.7\r
+X-Spam-Level: \r
+X-Spam-Status: No, score=-0.7 tagged_above=-999 required=5\r
+ tests=[RCVD_IN_DNSWL_LOW=-0.7] autolearn=disabled\r
+Received: from olra.theworths.org ([127.0.0.1])\r
+ by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)\r
+ with ESMTP id vqFQqBI99Jed for <notmuch@notmuchmail.org>;\r
+ Sat, 1 Dec 2012 18:40:15 -0800 (PST)\r
+Received: from dmz-mailsec-scanner-8.mit.edu (DMZ-MAILSEC-SCANNER-8.MIT.EDU\r
+ [18.7.68.37])\r
+ by olra.theworths.org (Postfix) with ESMTP id 38A3F431FAF\r
+ for <notmuch@notmuchmail.org>; Sat, 1 Dec 2012 18:40:14 -0800 (PST)\r
+X-AuditID: 12074425-b7f606d0000008ea-2d-50babf8d90e3\r
+Received: from mailhub-auth-2.mit.edu ( [18.7.62.36])\r
+ by dmz-mailsec-scanner-8.mit.edu (Symantec Messaging Gateway) with SMTP\r
+ id 49.75.02282.D8FBAB05; Sat, 1 Dec 2012 21:40:13 -0500 (EST)\r
+Received: from outgoing.mit.edu (OUTGOING-AUTH.MIT.EDU [18.7.22.103])\r
+ by mailhub-auth-2.mit.edu (8.13.8/8.9.2) with ESMTP id qB22eBx7019891; \r
+ Sat, 1 Dec 2012 21:40:11 -0500\r
+Received: from drake.dyndns.org\r
+ (209-6-116-242.c3-0.arl-ubr1.sbo-arl.ma.cable.rcn.com\r
+ [209.6.116.242]) (authenticated bits=0)\r
+ (User authenticated as amdragon@ATHENA.MIT.EDU)\r
+ by outgoing.mit.edu (8.13.6/8.12.4) with ESMTP id qB22e6bQ025593\r
+ (version=TLSv1/SSLv3 cipher=AES256-SHA bits=256 verify=NOT);\r
+ Sat, 1 Dec 2012 21:40:10 -0500 (EST)\r
+Received: from amthrax by drake.dyndns.org with local (Exim 4.77)\r
+ (envelope-from <amdragon@mit.edu>)\r
+ id 1TezTR-0000xR-PI; Sat, 01 Dec 2012 21:40:05 -0500\r
+From: Austin Clements <amdragon@MIT.EDU>\r
+To: notmuch@notmuchmail.org\r
+Subject: [PATCH 01/10] cli: Framework for structured output versioning\r
+Date: Sat, 1 Dec 2012 21:39:53 -0500\r
+Message-Id: <1354416002-3557-1-git-send-email-amdragon@mit.edu>\r
+X-Mailer: git-send-email 1.7.10.4\r
+MIME-Version: 1.0\r
+Content-Type: text/plain; charset=UTF-8\r
+Content-Transfer-Encoding: 8bit\r
+X-Brightmail-Tracker:\r
+ H4sIAAAAAAAAA+NgFvrAIsWRmVeSWpSXmKPExsUixG6notu7f1eAQc8Ec4vrN2cyOzB6PFt1\r
+ izmAMYrLJiU1J7MstUjfLoErY//Lc+wFsw0qVh3bz9rA2KXexcjJISFgIvHz/l9GCFtM4sK9\r
+ 9WxdjFwcQgL7GCWu/9nIApIQEljPKHHzQQJE4iGTxMeDs1khEnMZJZbdiACx2QQ0JLbtXw42\r
+ SURAWmLnXZAaDg5mATWJP10qIGFhgTSJR2+fsoPYLAKqEnsnt7KDlPAK2EvM2B4GcYOiRPez\r
+ CWwgNq+AoMTJmU9YIKaoS6yfJwQSZhaQl2jeOpt5AqPALCRVsxCqZiGpWsDIvIpRNiW3Sjc3\r
+ MTOnODVZtzg5MS8vtUjXQi83s0QvNaV0EyM4GF1UdzBOOKR0iFGAg1GJhzdizq4AIdbEsuLK\r
+ 3EOMkhxMSqK8V3YAhfiS8lMqMxKLM+KLSnNSiw8xSnAwK4nwspgA5XhTEiurUovyYVLSHCxK\r
+ 4rw3Um76CwmkJ5akZqemFqQWwWRlODiUJHir9wE1ChalpqdWpGXmlCCkmTg4QYbzAA2fBlLD\r
+ W1yQmFucmQ6RP8VozDFnZvsTRo6Fa4CkEEtefl6qlDhvJ0ipAEhpRmke3DRYQnnFKA70nDDv\r
+ YZAqHmAygpv3CmgVE9CqN8u2g6wqSURISTUwhphaBv9S6TaycH1SxdO544ywVdjPlY2yrI+d\r
+ 2Dn+HfyklR3S/Gu/1M3oyL8rc7aH3nj++mBD1ykDBSn7frNJ8mdNww6e3Bm/7CLjzo5PqQ7T\r
+ 6lTXmTz5uYvx66cDRrPLVIJ5G9hXclzNO7RcnKv3KJedpfDV9jedP6zYrFqVzQ+nsQUFGOxS\r
+ YinOSDTUYi4qTgQA/YgtFgMDAAA=\r
+X-BeenThere: notmuch@notmuchmail.org\r
+X-Mailman-Version: 2.1.13\r
+Precedence: list\r
+List-Id: "Use and development of the notmuch mail system."\r
+ <notmuch.notmuchmail.org>\r
+List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
+ <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
+List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
+List-Post: <mailto:notmuch@notmuchmail.org>\r
+List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
+List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
+ <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
+X-List-Received-Date: Sun, 02 Dec 2012 02:40:19 -0000\r
+\r
+Currently there is a period of pain whenever we make\r
+backward-incompatible changes to the structured output format. This\r
+series of patches introduces a way for CLI callers to request a\r
+specific schema version on the command line and to determine if the\r
+CLI does not supported the requested version (and perhaps present a\r
+useful diagnostic to the user). Since the caller requests a schema\r
+version, it's also possible for the CLI to support multiple\r
+incompatible versions simultaneously, unlike the alternate approach of\r
+including version information in the output.\r
+\r
+This patch lays the groundwork by introducing a versioning convention,\r
+standard exit codes, and a utility function to check the requested\r
+version and produce standardized diagnostic messages and exit\r
+statuses.\r
+---\r
+ Makefile.local | 1 +\r
+ notmuch-client.h | 46 ++++++++++++++++++++++++++++++++++++++++++++++\r
+ notmuch.c | 3 +++\r
+ schema.c | 46 ++++++++++++++++++++++++++++++++++++++++++++++\r
+ 4 files changed, 96 insertions(+)\r
+ create mode 100644 schema.c\r
+\r
+diff --git a/Makefile.local b/Makefile.local\r
+index 2b91946..bfed50e 100644\r
+--- a/Makefile.local\r
++++ b/Makefile.local\r
+@@ -274,6 +274,7 @@ notmuch_client_srcs = \\r
+ query-string.c \\r
+ mime-node.c \\r
+ crypto.c \\r
++ schema.c \\r
+ \r
+ notmuch_client_modules = $(notmuch_client_srcs:.c=.o)\r
+ \r
+diff --git a/notmuch-client.h b/notmuch-client.h\r
+index ae9344b..14e7363 100644\r
+--- a/notmuch-client.h\r
++++ b/notmuch-client.h\r
+@@ -117,6 +117,52 @@ chomp_newline (char *str)\r
+ str[strlen(str)-1] = '\0';\r
+ }\r
+ \r
++/* Exit status code indicating the requested schema version is too old\r
++ * (support for that version has been dropped). CLI code should use\r
++ * notmuch_exit_if_unsupported_schema rather than directly exiting\r
++ * with this code.\r
++ */\r
++#define NOTMUCH_EXIT_SCHEMA_TOO_OLD 20\r
++/* Exit status code indicating the requested schema version is newer\r
++ * than the version supported by the CLI. CLI code should use\r
++ * notmuch_exit_if_unsupported_schema rather than directly exiting\r
++ * with this code.\r
++ */\r
++#define NOTMUCH_EXIT_SCHEMA_TOO_NEW 21\r
++\r
++/* The version number of the current structured output schema.\r
++ * Requests for schema versions above this will return an error.\r
++ * Backwards-incompatible changes such as removing map fields,\r
++ * changing the meaning of map fields, or changing the meanings of\r
++ * list elements should increase this. New map fields can be added\r
++ * without increasing this. Note that different notmuch commands may\r
++ * support different backwards-compatible version numbers, but the\r
++ * "current" version is consistent across all parts of the schema.\r
++ */\r
++#define NOTMUCH_SCHEMA_CUR 1\r
++\r
++/* The schema version requested by the caller on the command line. If\r
++ * no schema version is requested, this should be set to\r
++ * NOTMUCH_SCHEMA_CUR. This is global---rather than per\r
++ * command---because commands can share structured output code.\r
++ */\r
++extern int notmuch_schema_version;\r
++\r
++/* Commands that support structured output should support the\r
++ * following argument\r
++ * { NOTMUCH_OPT_INT, ¬much_schema_version, "use-schema", 0, 0 }\r
++ * and should invoke notmuch_exit_if_unsupported_schema to check\r
++ * against the per-command minimum supported schema version and the\r
++ * global maximum supported schema version. If notmuch_schema_version\r
++ * is outside the supported range, this will print a detailed\r
++ * diagnostic message for the user and exit with\r
++ * NOTMUCH_EXIT_SCHEMA_TOO_{OLD,NEW} to inform the invoking program of\r
++ * the problem.\r
++ */\r
++void\r
++notmuch_exit_if_unsupported_schema (const char *command,\r
++ int min_schema_version);\r
++\r
+ notmuch_crypto_context_t *\r
+ notmuch_crypto_get_context (notmuch_crypto_t *crypto, const char *protocol);\r
+ \r
+diff --git a/notmuch.c b/notmuch.c\r
+index 477a09c..ed860f2 100644\r
+--- a/notmuch.c\r
++++ b/notmuch.c\r
+@@ -242,6 +242,9 @@ main (int argc, char *argv[])\r
+ g_mime_init (0);\r
+ g_type_init ();\r
+ \r
++ /* Globally default to the current schema version. */\r
++ notmuch_schema_version = NOTMUCH_SCHEMA_CUR;\r
++\r
+ if (argc == 1)\r
+ return notmuch (local);\r
+ \r
+diff --git a/schema.c b/schema.c\r
+new file mode 100644\r
+index 0000000..4b6c4fa\r
+--- /dev/null\r
++++ b/schema.c\r
+@@ -0,0 +1,46 @@\r
++/* notmuch - Not much of an email program, (just index and search)\r
++ *\r
++ * This file is part of notmuch.\r
++ *\r
++ * Copyright © 2012 Austin Clements\r
++ *\r
++ * This program is free software: you can redistribute it and/or modify\r
++ * it under the terms of the GNU General Public License as published by\r
++ * the Free Software Foundation, either version 3 of the License, or\r
++ * (at your option) any later version.\r
++ *\r
++ * This program is distributed in the hope that it will be useful,\r
++ * but WITHOUT ANY WARRANTY; without even the implied warranty of\r
++ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\r
++ * GNU General Public License for more details.\r
++ *\r
++ * You should have received a copy of the GNU General Public License\r
++ * along with this program. If not, see http://www.gnu.org/licenses/ .\r
++ *\r
++ * Author: Austin Clements <aclements@csail.mit.edu>\r
++ */\r
++\r
++#include "notmuch-client.h"\r
++\r
++int notmuch_schema_version;\r
++\r
++void\r
++notmuch_exit_if_unsupported_schema (const char *command,\r
++ int min_schema_version)\r
++{\r
++ if (notmuch_schema_version > NOTMUCH_SCHEMA_CUR) {\r
++ fprintf (stderr, "\\r
++A caller requested a newer output format (schema version %d) than\n\\r
++supported by the notmuch CLI (which supports up to version %d). You\n\\r
++may need to upgrade your notmuch CLI.\n",\r
++ notmuch_schema_version, NOTMUCH_SCHEMA_CUR);\r
++ exit (NOTMUCH_EXIT_SCHEMA_TOO_NEW);\r
++ } else if (notmuch_schema_version < min_schema_version) {\r
++ fprintf (stderr, "\\r
++A caller requested an older output format (schema version %d) than\n\\r
++supported by the %s command of the notmuch CLI (which requires at\n\\r
++least version %d). You may need to upgrade your notmuch front-end.\n",\r
++ notmuch_schema_version, command, min_schema_version);\r
++ exit (NOTMUCH_EXIT_SCHEMA_TOO_OLD);\r
++ }\r
++}\r
+-- \r
+1.7.10.4\r
+\r
projects / notmuch-archives.git / commitdiff