From bb5b1941db3f5681b92a1787d1c9c958988519a5 Mon Sep 17 00:00:00 2001 From: Austin Clements Date: Sun, 2 Dec 2012 21:39:53 +1900 Subject: [PATCH] [PATCH 01/10] cli: Framework for structured output versioning --- ab/c3ea974ad29590e099e5478cee57e4b3c93797 | 234 ++++++++++++++++++++++ 1 file changed, 234 insertions(+) create mode 100644 ab/c3ea974ad29590e099e5478cee57e4b3c93797 diff --git a/ab/c3ea974ad29590e099e5478cee57e4b3c93797 b/ab/c3ea974ad29590e099e5478cee57e4b3c93797 new file mode 100644 index 000000000..33424cd85 --- /dev/null +++ b/ab/c3ea974ad29590e099e5478cee57e4b3c93797 @@ -0,0 +1,234 @@ +Return-Path: +X-Original-To: notmuch@notmuchmail.org +Delivered-To: notmuch@notmuchmail.org +Received: from localhost (localhost [127.0.0.1]) + by olra.theworths.org (Postfix) with ESMTP id 3E2F5429E39 + for ; Sat, 1 Dec 2012 18:40:19 -0800 (PST) +X-Virus-Scanned: Debian amavisd-new at olra.theworths.org +X-Spam-Flag: NO +X-Spam-Score: -0.7 +X-Spam-Level: +X-Spam-Status: No, score=-0.7 tagged_above=-999 required=5 + tests=[RCVD_IN_DNSWL_LOW=-0.7] autolearn=disabled +Received: from olra.theworths.org ([127.0.0.1]) + by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024) + with ESMTP id vqFQqBI99Jed for ; + Sat, 1 Dec 2012 18:40:15 -0800 (PST) +Received: from dmz-mailsec-scanner-8.mit.edu (DMZ-MAILSEC-SCANNER-8.MIT.EDU + [18.7.68.37]) + by olra.theworths.org (Postfix) with ESMTP id 38A3F431FAF + for ; Sat, 1 Dec 2012 18:40:14 -0800 (PST) +X-AuditID: 12074425-b7f606d0000008ea-2d-50babf8d90e3 +Received: from mailhub-auth-2.mit.edu ( [18.7.62.36]) + by dmz-mailsec-scanner-8.mit.edu (Symantec Messaging Gateway) with SMTP + id 49.75.02282.D8FBAB05; Sat, 1 Dec 2012 21:40:13 -0500 (EST) +Received: from outgoing.mit.edu (OUTGOING-AUTH.MIT.EDU [18.7.22.103]) + by mailhub-auth-2.mit.edu (8.13.8/8.9.2) with ESMTP id qB22eBx7019891; + Sat, 1 Dec 2012 21:40:11 -0500 +Received: from drake.dyndns.org + (209-6-116-242.c3-0.arl-ubr1.sbo-arl.ma.cable.rcn.com + [209.6.116.242]) (authenticated bits=0) + (User authenticated as amdragon@ATHENA.MIT.EDU) + by outgoing.mit.edu (8.13.6/8.12.4) with ESMTP id qB22e6bQ025593 + (version=TLSv1/SSLv3 cipher=AES256-SHA bits=256 verify=NOT); + Sat, 1 Dec 2012 21:40:10 -0500 (EST) +Received: from amthrax by drake.dyndns.org with local (Exim 4.77) + (envelope-from ) + id 1TezTR-0000xR-PI; Sat, 01 Dec 2012 21:40:05 -0500 +From: Austin Clements +To: notmuch@notmuchmail.org +Subject: [PATCH 01/10] cli: Framework for structured output versioning +Date: Sat, 1 Dec 2012 21:39:53 -0500 +Message-Id: <1354416002-3557-1-git-send-email-amdragon@mit.edu> +X-Mailer: git-send-email 1.7.10.4 +MIME-Version: 1.0 +Content-Type: text/plain; charset=UTF-8 +Content-Transfer-Encoding: 8bit +X-Brightmail-Tracker: + H4sIAAAAAAAAA+NgFvrAIsWRmVeSWpSXmKPExsUixG6notu7f1eAQc8Ec4vrN2cyOzB6PFt1 + izmAMYrLJiU1J7MstUjfLoErY//Lc+wFsw0qVh3bz9rA2KXexcjJISFgIvHz/l9GCFtM4sK9 + 9WxdjFwcQgL7GCWu/9nIApIQEljPKHHzQQJE4iGTxMeDs1khEnMZJZbdiACx2QQ0JLbtXw42 + SURAWmLnXZAaDg5mATWJP10qIGFhgTSJR2+fsoPYLAKqEnsnt7KDlPAK2EvM2B4GcYOiRPez + CWwgNq+AoMTJmU9YIKaoS6yfJwQSZhaQl2jeOpt5AqPALCRVsxCqZiGpWsDIvIpRNiW3Sjc3 + MTOnODVZtzg5MS8vtUjXQi83s0QvNaV0EyM4GF1UdzBOOKR0iFGAg1GJhzdizq4AIdbEsuLK + 3EOMkhxMSqK8V3YAhfiS8lMqMxKLM+KLSnNSiw8xSnAwK4nwspgA5XhTEiurUovyYVLSHCxK + 4rw3Um76CwmkJ5akZqemFqQWwWRlODiUJHir9wE1ChalpqdWpGXmlCCkmTg4QYbzAA2fBlLD + W1yQmFucmQ6RP8VozDFnZvsTRo6Fa4CkEEtefl6qlDhvJ0ipAEhpRmke3DRYQnnFKA70nDDv + YZAqHmAygpv3CmgVE9CqN8u2g6wqSURISTUwhphaBv9S6TaycH1SxdO544ywVdjPlY2yrI+d + 2Dn+HfyklR3S/Gu/1M3oyL8rc7aH3nj++mBD1ykDBSn7frNJ8mdNww6e3Bm/7CLjzo5PqQ7T + 6lTXmTz5uYvx66cDRrPLVIJ5G9hXclzNO7RcnKv3KJedpfDV9jedP6zYrFqVzQ+nsQUFGOxS + YinOSDTUYi4qTgQA/YgtFgMDAAA= +X-BeenThere: notmuch@notmuchmail.org +X-Mailman-Version: 2.1.13 +Precedence: list +List-Id: "Use and development of the notmuch mail system." + +List-Unsubscribe: , + +List-Archive: +List-Post: +List-Help: +List-Subscribe: , + +X-List-Received-Date: Sun, 02 Dec 2012 02:40:19 -0000 + +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, ¬much_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 ++ */ ++ ++#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 + -- 2.26.2