[PATCH 00/10] CLI output versioning

diff --git a/9f/a2b0331ee5d96c503437a5ac3f118a5bc1c242 b/9f/a2b0331ee5d96c503437a5ac3f118a5bc1c242
new file mode 100644 (file)
index 0000000..b402ad2
--- /dev/null
+++ b/9f/a2b0331ee5d96c503437a5ac3f118a5bc1c242
@@ -0,0 +1,97 @@
+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 F0958431FBC\r
+       for <notmuch@notmuchmail.org>; Sun,  2 Dec 2012 16:59:03 -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 irq0lpjO9sZX for <notmuch@notmuchmail.org>;\r
+       Sun,  2 Dec 2012 16:59:03 -0800 (PST)\r
+Received: from dmz-mailsec-scanner-1.mit.edu (DMZ-MAILSEC-SCANNER-1.MIT.EDU\r
+       [18.9.25.12])\r
+       by olra.theworths.org (Postfix) with ESMTP id 71EB1429E2E\r
+       for <notmuch@notmuchmail.org>; Sun,  2 Dec 2012 16:58:59 -0800 (PST)\r
+X-AuditID: 1209190c-b7f886d000000936-48-50bbf9527ced\r
+Received: from mailhub-auth-4.mit.edu ( [18.7.62.39])\r
+       by dmz-mailsec-scanner-1.mit.edu (Symantec Messaging Gateway) with SMTP\r
+       id 0F.45.02358.259FBB05; Sun,  2 Dec 2012 19:58:58 -0500 (EST)\r
+Received: from outgoing.mit.edu (OUTGOING-AUTH.MIT.EDU [18.7.22.103])\r
+       by mailhub-auth-4.mit.edu (8.13.8/8.9.2) with ESMTP id qB30wvcX018780\r
+       for <notmuch@notmuchmail.org>; Sun, 2 Dec 2012 19:58:58 -0500\r
+Received: from awakening.csail.mit.edu (awakening.csail.mit.edu [18.26.4.91])\r
+       (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 qB30wtvE011024\r
+       (version=TLSv1/SSLv3 cipher=DHE-RSA-AES128-SHA bits=128 verify=NOT)\r
+       for <notmuch@notmuchmail.org>; Sun, 2 Dec 2012 19:58:57 -0500 (EST)\r
+Received: from amthrax by awakening.csail.mit.edu with local (Exim 4.80)\r
+       (envelope-from <amdragon@mit.edu>) id 1TfKN5-0006SF-ED\r
+       for notmuch@notmuchmail.org; Sun, 02 Dec 2012 19:58:55 -0500\r
+From: Austin Clements <amdragon@MIT.EDU>\r
+To: notmuch@notmuchmail.org\r
+Subject: [PATCH 00/10] CLI output versioning\r
+In-Reply-To: <1354416002-3557-1-git-send-email-amdragon@mit.edu>\r
+References: <1354416002-3557-1-git-send-email-amdragon@mit.edu>\r
+User-Agent: Notmuch/0.14+100~gcb9b0b0 (http://notmuchmail.org) Emacs/23.4.1\r
+       (i486-pc-linux-gnu)\r
+Date: Sun, 02 Dec 2012 19:58:55 -0500\r
+Message-ID: <87pq2sx86o.fsf@awakening.csail.mit.edu>\r
+MIME-Version: 1.0\r
+Content-Type: text/plain; charset=us-ascii\r
+X-Brightmail-Tracker:\r
+ H4sIAAAAAAAAA+NgFrrKIsWRmVeSWpSXmKPExsUixG6nrhv0c3eAQfMROYvrN2cyOzB6PFt1\r
+       izmAMYrLJiU1J7MstUjfLoEro6V9N1vBd86KZWu+sjYwTuPoYuTkkBAwkTjcMo8RwhaTuHBv\r
+       PVsXIxeHkMA+Roll95YzQThnGSWa+x+zQjjvmCRuX+qAyhxilFh7aBoTSD+bgIbEtv3LwWaJ\r
+       CEhL7Lw7mxXEFhbQkTj+7h/QXA4OTgEHiRXdPCBhIQF7if+/r4GFRQXiJS4vVQAJswioSsxt\r
+       OcoCEuYFum7jd0OQMK+AoMTJmU9YQGxmAS2JG/9eMk1gFJiFJDULSWoBI9MqRtmU3Crd3MTM\r
+       nOLUZN3i5MS8vNQiXUO93MwSvdSU0k2MoNDjlOTZwfjmoNIhRgEORiUe3gdfdgcIsSaWFVfm\r
+       HmKU5GBSEuVt/wYU4kvKT6nMSCzOiC8qzUktBnqbg1lJhHdxBVCONyWxsiq1KB8mJc3BoiTO\r
+       eznlpr+QQHpiSWp2ampBahFMVoaDQ0mCt/gHUKNgUWp6akVaZk4JQpqJgxNkOA/Q8FiQGt7i\r
+       gsTc4sx0iPwpRkUpcd5ZIAkBkERGaR5cLyw1vGIUB3pFmJcHpIoHmFbgul8BDWYCGvxCCGxw\r
+       SSJCSqqBMTRP6sO3J21vkz/mG65Zv8Bz8rmpvtnJ759GfC2P7TF+unuy5yluuy0yunPP3Uo5\r
+       tjNn8U/e6ZOUvWfd7J/1+Ca/kN217eudjt9UO7nbje9L9/8lsnd3FloJ/NzutUNng8i8wPBd\r
+       3nyaL0Ptc/SfeX2b9mbRj4or7R37Fy1YHbM0Lf+ri7zvWS4lluKMREMt5qLiRACmvkQ/6AIA        AA==\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: Mon, 03 Dec 2012 00:59:04 -0000\r
+\r
+(Sorry; I forgot to include a cover letter.)\r
+\r
+This series is intended to help with our long-standing output format\r
+versioning issue.  While the JSON format is amenable to extension,\r
+there's still a high barrier to extensions because of the need to\r
+support them going forward, and an even higher barrier to modifications\r
+that break backwards compatibility.  Versioning will make the format\r
+more dynamic, enabling us to easily improve and iterate on it.  It will\r
+also address the slew of confusing bugs that people encounter when they\r
+use a mismatched CLI and front-end.\r
+\r
+On IRC we've talking about adding version information to the output\r
+format itself.  This series takes a different and, I think, better\r
+approach: callers request a specific output format version on the\r
+command line.  This allows notmuch to remain backwards compatible with\r
+older format versions when it's easy or necessary.  This also doesn't\r
+require shoehorning a version number into the output, which would be\r
+awkward for both the CLI and the consumer.\r
+\r
+I called the argument --use-schema, but I'm open to other suggestions.\r
+--use-schema is technically accurate, but perhaps not as self-describing\r
+as something like --schema-version or --format-version (to parallel\r
+--format).\r