ab/c3ea974ad29590e099e5478cee57e4b3c93797

   1 Return-Path: <amdragon@mit.edu>\r
   2 X-Original-To: notmuch@notmuchmail.org\r
   3 Delivered-To: notmuch@notmuchmail.org\r
   4 Received: from localhost (localhost [127.0.0.1])\r
   5         by olra.theworths.org (Postfix) with ESMTP id 3E2F5429E39\r
   6         for <notmuch@notmuchmail.org>; Sat,  1 Dec 2012 18:40:19 -0800 (PST)\r
   7 X-Virus-Scanned: Debian amavisd-new at olra.theworths.org\r
   8 X-Spam-Flag: NO\r
   9 X-Spam-Score: -0.7\r
  10 X-Spam-Level: \r
  11 X-Spam-Status: No, score=-0.7 tagged_above=-999 required=5\r
  12         tests=[RCVD_IN_DNSWL_LOW=-0.7] autolearn=disabled\r
  13 Received: from olra.theworths.org ([127.0.0.1])\r
  14         by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)\r
  15         with ESMTP id vqFQqBI99Jed for <notmuch@notmuchmail.org>;\r
  16         Sat,  1 Dec 2012 18:40:15 -0800 (PST)\r
  17 Received: from dmz-mailsec-scanner-8.mit.edu (DMZ-MAILSEC-SCANNER-8.MIT.EDU\r
  18         [18.7.68.37])\r
  19         by olra.theworths.org (Postfix) with ESMTP id 38A3F431FAF\r
  20         for <notmuch@notmuchmail.org>; Sat,  1 Dec 2012 18:40:14 -0800 (PST)\r
  21 X-AuditID: 12074425-b7f606d0000008ea-2d-50babf8d90e3\r
  22 Received: from mailhub-auth-2.mit.edu ( [18.7.62.36])\r
  23         by dmz-mailsec-scanner-8.mit.edu (Symantec Messaging Gateway) with SMTP\r
  24         id 49.75.02282.D8FBAB05; Sat,  1 Dec 2012 21:40:13 -0500 (EST)\r
  25 Received: from outgoing.mit.edu (OUTGOING-AUTH.MIT.EDU [18.7.22.103])\r
  26         by mailhub-auth-2.mit.edu (8.13.8/8.9.2) with ESMTP id qB22eBx7019891; \r
  27         Sat, 1 Dec 2012 21:40:11 -0500\r
  28 Received: from drake.dyndns.org\r
  29         (209-6-116-242.c3-0.arl-ubr1.sbo-arl.ma.cable.rcn.com\r
  30         [209.6.116.242]) (authenticated bits=0)\r
  31         (User authenticated as amdragon@ATHENA.MIT.EDU)\r
  32         by outgoing.mit.edu (8.13.6/8.12.4) with ESMTP id qB22e6bQ025593\r
  33         (version=TLSv1/SSLv3 cipher=AES256-SHA bits=256 verify=NOT);\r
  34         Sat, 1 Dec 2012 21:40:10 -0500 (EST)\r
  35 Received: from amthrax by drake.dyndns.org with local (Exim 4.77)\r
  36         (envelope-from <amdragon@mit.edu>)\r
  37         id 1TezTR-0000xR-PI; Sat, 01 Dec 2012 21:40:05 -0500\r
  38 From: Austin Clements <amdragon@MIT.EDU>\r
  39 To: notmuch@notmuchmail.org\r
  40 Subject: [PATCH 01/10] cli: Framework for structured output versioning\r
  41 Date: Sat,  1 Dec 2012 21:39:53 -0500\r
  42 Message-Id: <1354416002-3557-1-git-send-email-amdragon@mit.edu>\r
  43 X-Mailer: git-send-email 1.7.10.4\r
  44 MIME-Version: 1.0\r
  45 Content-Type: text/plain; charset=UTF-8\r
  46 Content-Transfer-Encoding: 8bit\r
  47 X-Brightmail-Tracker:\r
  48  H4sIAAAAAAAAA+NgFvrAIsWRmVeSWpSXmKPExsUixG6notu7f1eAQc8Ec4vrN2cyOzB6PFt1\r
  49         izmAMYrLJiU1J7MstUjfLoErY//Lc+wFsw0qVh3bz9rA2KXexcjJISFgIvHz/l9GCFtM4sK9\r
  50         9WxdjFwcQgL7GCWu/9nIApIQEljPKHHzQQJE4iGTxMeDs1khEnMZJZbdiACx2QQ0JLbtXw42\r
  51         SURAWmLnXZAaDg5mATWJP10qIGFhgTSJR2+fsoPYLAKqEnsnt7KDlPAK2EvM2B4GcYOiRPez\r
  52         CWwgNq+AoMTJmU9YIKaoS6yfJwQSZhaQl2jeOpt5AqPALCRVsxCqZiGpWsDIvIpRNiW3Sjc3\r
  53         MTOnODVZtzg5MS8vtUjXQi83s0QvNaV0EyM4GF1UdzBOOKR0iFGAg1GJhzdizq4AIdbEsuLK\r
  54         3EOMkhxMSqK8V3YAhfiS8lMqMxKLM+KLSnNSiw8xSnAwK4nwspgA5XhTEiurUovyYVLSHCxK\r
  55         4rw3Um76CwmkJ5akZqemFqQWwWRlODiUJHir9wE1ChalpqdWpGXmlCCkmTg4QYbzAA2fBlLD\r
  56         W1yQmFucmQ6RP8VozDFnZvsTRo6Fa4CkEEtefl6qlDhvJ0ipAEhpRmke3DRYQnnFKA70nDDv\r
  57         YZAqHmAygpv3CmgVE9CqN8u2g6wqSURISTUwhphaBv9S6TaycH1SxdO544ywVdjPlY2yrI+d\r
  58         2Dn+HfyklR3S/Gu/1M3oyL8rc7aH3nj++mBD1ykDBSn7frNJ8mdNww6e3Bm/7CLjzo5PqQ7T\r
  59         6lTXmTz5uYvx66cDRrPLVIJ5G9hXclzNO7RcnKv3KJedpfDV9jedP6zYrFqVzQ+nsQUFGOxS\r
  60         YinOSDTUYi4qTgQA/YgtFgMDAAA=\r
  61 X-BeenThere: notmuch@notmuchmail.org\r
  62 X-Mailman-Version: 2.1.13\r
  63 Precedence: list\r
  64 List-Id: "Use and development of the notmuch mail system."\r
  65         <notmuch.notmuchmail.org>\r
  66 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
  67         <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
  68 List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
  69 List-Post: <mailto:notmuch@notmuchmail.org>\r
  70 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
  71 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
  72         <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
  73 X-List-Received-Date: Sun, 02 Dec 2012 02:40:19 -0000\r
  74 \r
  75 Currently there is a period of pain whenever we make\r
  76 backward-incompatible changes to the structured output format.  This\r
  77 series of patches introduces a way for CLI callers to request a\r
  78 specific schema version on the command line and to determine if the\r
  79 CLI does not supported the requested version (and perhaps present a\r
  80 useful diagnostic to the user).  Since the caller requests a schema\r
  81 version, it's also possible for the CLI to support multiple\r
  82 incompatible versions simultaneously, unlike the alternate approach of\r
  83 including version information in the output.\r
  84 \r
  85 This patch lays the groundwork by introducing a versioning convention,\r
  86 standard exit codes, and a utility function to check the requested\r
  87 version and produce standardized diagnostic messages and exit\r
  88 statuses.\r
  89 ---\r
  90  Makefile.local   |    1 +\r
  91  notmuch-client.h |   46 ++++++++++++++++++++++++++++++++++++++++++++++\r
  92  notmuch.c        |    3 +++\r
  93  schema.c         |   46 ++++++++++++++++++++++++++++++++++++++++++++++\r
  94  4 files changed, 96 insertions(+)\r
  95  create mode 100644 schema.c\r
  96 \r
  97 diff --git a/Makefile.local b/Makefile.local\r
  98 index 2b91946..bfed50e 100644\r
  99 --- a/Makefile.local\r
 100 +++ b/Makefile.local\r
 101 @@ -274,6 +274,7 @@ notmuch_client_srcs =               \\r
 102         query-string.c          \\r
 103         mime-node.c             \\r
 104         crypto.c                \\r
 105 +       schema.c                \\r
 106  \r
 107  notmuch_client_modules = $(notmuch_client_srcs:.c=.o)\r
 108  \r
 109 diff --git a/notmuch-client.h b/notmuch-client.h\r
 110 index ae9344b..14e7363 100644\r
 111 --- a/notmuch-client.h\r
 112 +++ b/notmuch-client.h\r
 113 @@ -117,6 +117,52 @@ chomp_newline (char *str)\r
 114         str[strlen(str)-1] = '\0';\r
 115  }\r
 116  \r
 117 +/* Exit status code indicating the requested schema version is too old\r
 118 + * (support for that version has been dropped).  CLI code should use\r
 119 + * notmuch_exit_if_unsupported_schema rather than directly exiting\r
 120 + * with this code.\r
 121 + */\r
 122 +#define NOTMUCH_EXIT_SCHEMA_TOO_OLD 20\r
 123 +/* Exit status code indicating the requested schema version is newer\r
 124 + * than the version supported by the CLI.  CLI code should use\r
 125 + * notmuch_exit_if_unsupported_schema rather than directly exiting\r
 126 + * with this code.\r
 127 + */\r
 128 +#define NOTMUCH_EXIT_SCHEMA_TOO_NEW 21\r
 129 +\r
 130 +/* The version number of the current structured output schema.\r
 131 + * Requests for schema versions above this will return an error.\r
 132 + * Backwards-incompatible changes such as removing map fields,\r
 133 + * changing the meaning of map fields, or changing the meanings of\r
 134 + * list elements should increase this.  New map fields can be added\r
 135 + * without increasing this.  Note that different notmuch commands may\r
 136 + * support different backwards-compatible version numbers, but the\r
 137 + * "current" version is consistent across all parts of the schema.\r
 138 + */\r
 139 +#define NOTMUCH_SCHEMA_CUR 1\r
 140 +\r
 141 +/* The schema version requested by the caller on the command line.  If\r
 142 + * no schema version is requested, this should be set to\r
 143 + * NOTMUCH_SCHEMA_CUR.  This is global---rather than per\r
 144 + * command---because commands can share structured output code.\r
 145 + */\r
 146 +extern int notmuch_schema_version;\r
 147 +\r
 148 +/* Commands that support structured output should support the\r
 149 + * following argument\r
 150 + *  { NOTMUCH_OPT_INT, &notmuch_schema_version, "use-schema", 0, 0 }\r
 151 + * and should invoke notmuch_exit_if_unsupported_schema to check\r
 152 + * against the per-command minimum supported schema version and the\r
 153 + * global maximum supported schema version.  If notmuch_schema_version\r
 154 + * is outside the supported range, this will print a detailed\r
 155 + * diagnostic message for the user and exit with\r
 156 + * NOTMUCH_EXIT_SCHEMA_TOO_{OLD,NEW} to inform the invoking program of\r
 157 + * the problem.\r
 158 + */\r
 159 +void\r
 160 +notmuch_exit_if_unsupported_schema (const char *command,\r
 161 +                                   int min_schema_version);\r
 162 +\r
 163  notmuch_crypto_context_t *\r
 164  notmuch_crypto_get_context (notmuch_crypto_t *crypto, const char *protocol);\r
 165  \r
 166 diff --git a/notmuch.c b/notmuch.c\r
 167 index 477a09c..ed860f2 100644\r
 168 --- a/notmuch.c\r
 169 +++ b/notmuch.c\r
 170 @@ -242,6 +242,9 @@ main (int argc, char *argv[])\r
 171      g_mime_init (0);\r
 172      g_type_init ();\r
 173  \r
 174 +    /* Globally default to the current schema version. */\r
 175 +    notmuch_schema_version = NOTMUCH_SCHEMA_CUR;\r
 176 +\r
 177      if (argc == 1)\r
 178         return notmuch (local);\r
 179  \r
 180 diff --git a/schema.c b/schema.c\r
 181 new file mode 100644\r
 182 index 0000000..4b6c4fa\r
 183 --- /dev/null\r
 184 +++ b/schema.c\r
 185 @@ -0,0 +1,46 @@\r
 186 +/* notmuch - Not much of an email program, (just index and search)\r
 187 + *\r
 188 + * This file is part of notmuch.\r
 189 + *\r
 190 + * Copyright © 2012 Austin Clements\r
 191 + *\r
 192 + * This program is free software: you can redistribute it and/or modify\r
 193 + * it under the terms of the GNU General Public License as published by\r
 194 + * the Free Software Foundation, either version 3 of the License, or\r
 195 + * (at your option) any later version.\r
 196 + *\r
 197 + * This program is distributed in the hope that it will be useful,\r
 198 + * but WITHOUT ANY WARRANTY; without even the implied warranty of\r
 199 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\r
 200 + * GNU General Public License for more details.\r
 201 + *\r
 202 + * You should have received a copy of the GNU General Public License\r
 203 + * along with this program.  If not, see http://www.gnu.org/licenses/ .\r
 204 + *\r
 205 + * Author: Austin Clements <aclements@csail.mit.edu>\r
 206 + */\r
 207 +\r
 208 +#include "notmuch-client.h"\r
 209 +\r
 210 +int notmuch_schema_version;\r
 211 +\r
 212 +void\r
 213 +notmuch_exit_if_unsupported_schema (const char *command,\r
 214 +                                   int min_schema_version)\r
 215 +{\r
 216 +    if (notmuch_schema_version > NOTMUCH_SCHEMA_CUR) {\r
 217 +       fprintf (stderr, "\\r
 218 +A caller requested a newer output format (schema version %d) than\n\\r
 219 +supported by the notmuch CLI (which supports up to version %d).  You\n\\r
 220 +may need to upgrade your notmuch CLI.\n",\r
 221 +                notmuch_schema_version, NOTMUCH_SCHEMA_CUR);\r
 222 +       exit (NOTMUCH_EXIT_SCHEMA_TOO_NEW);\r
 223 +    } else if (notmuch_schema_version < min_schema_version) {\r
 224 +       fprintf (stderr, "\\r
 225 +A caller requested an older output format (schema version %d) than\n\\r
 226 +supported by the %s command of the notmuch CLI (which requires at\n\\r
 227 +least version %d).  You may need to upgrade your notmuch front-end.\n",\r
 228 +                notmuch_schema_version, command, min_schema_version);\r
 229 +       exit (NOTMUCH_EXIT_SCHEMA_TOO_OLD);\r
 230 +    }\r
 231 +}\r
 232 -- \r
 233 1.7.10.4\r
 234 \r