d7/735eda02225e56f64081d9d2975c5e039ef091

   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 74A2C431FAF\r
   6         for <notmuch@notmuchmail.org>; Sun, 24 Aug 2014 15:16:39 -0700 (PDT)\r
   7 X-Virus-Scanned: Debian amavisd-new at olra.theworths.org\r
   8 X-Spam-Flag: NO\r
   9 X-Spam-Score: -2.3\r
  10 X-Spam-Level: \r
  11 X-Spam-Status: No, score=-2.3 tagged_above=-999 required=5\r
  12         tests=[RCVD_IN_DNSWL_MED=-2.3] 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 wRZMQHwwvaQB for <notmuch@notmuchmail.org>;\r
  16         Sun, 24 Aug 2014 15:16:33 -0700 (PDT)\r
  17 Received: from dmz-mailsec-scanner-7.mit.edu (dmz-mailsec-scanner-7.mit.edu\r
  18         [18.7.68.36])\r
  19         (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits))\r
  20         (No client certificate requested)\r
  21         by olra.theworths.org (Postfix) with ESMTPS id 2481F431FAE\r
  22         for <notmuch@notmuchmail.org>; Sun, 24 Aug 2014 15:16:33 -0700 (PDT)\r
  23 X-AuditID: 12074424-f79346d000004923-57-53fa64406de8\r
  24 Received: from mailhub-auth-3.mit.edu ( [18.9.21.43])\r
  25         (using TLS with cipher AES256-SHA (256/256 bits))\r
  26         (Client did not present a certificate)\r
  27         by dmz-mailsec-scanner-7.mit.edu (Symantec Messaging Gateway) with SMTP\r
  28         id 18.D1.18723.0446AF35; Sun, 24 Aug 2014 18:16:32 -0400 (EDT)\r
  29 Received: from outgoing.mit.edu (outgoing-auth-1.mit.edu [18.9.28.11])\r
  30         by mailhub-auth-3.mit.edu (8.13.8/8.9.2) with ESMTP id s7OMGVWx001120; \r
  31         Sun, 24 Aug 2014 18:16:32 -0400\r
  32 Received: from awakening.csail.mit.edu (awakening.csail.mit.edu [18.26.4.91])\r
  33         (authenticated bits=0)\r
  34         (User authenticated as amdragon@ATHENA.MIT.EDU)\r
  35         by outgoing.mit.edu (8.13.8/8.12.4) with ESMTP id s7OMGTtC026194\r
  36         (version=TLSv1/SSLv3 cipher=DHE-RSA-AES128-SHA bits=128 verify=NOT);\r
  37         Sun, 24 Aug 2014 18:16:30 -0400\r
  38 Received: from amthrax by awakening.csail.mit.edu with local (Exim 4.80)\r
  39         (envelope-from <amdragon@mit.edu>)\r
  40         id 1XLg5N-0000eB-AW; Sun, 24 Aug 2014 18:16:29 -0400\r
  41 Date: Sun, 24 Aug 2014 18:16:29 -0400\r
  42 From: Austin Clements <amdragon@mit.edu>\r
  43 To: David Bremner <david@tethera.net>\r
  44 Subject: Re: [PATCH v3 04/13] lib: Database version 3: Introduce fine-grained\r
  45         "features"\r
  46 Message-ID: <20140824221629.GP3015@mit.edu>\r
  47 References: <1406859003-11561-1-git-send-email-amdragon@mit.edu>\r
  48         <1406859003-11561-5-git-send-email-amdragon@mit.edu>\r
  49         <87ppfqsv8s.fsf@maritornes.cs.unb.ca>\r
  50         <87fvgmg0tx.fsf@awakening.csail.mit.edu>\r
  51         <87zjeu4jyp.fsf@maritornes.cs.unb.ca>\r
  52 MIME-Version: 1.0\r
  53 Content-Type: text/plain; charset=us-ascii\r
  54 Content-Disposition: inline\r
  55 In-Reply-To: <87zjeu4jyp.fsf@maritornes.cs.unb.ca>\r
  56 User-Agent: Mutt/1.5.21 (2010-09-15)\r
  57 X-Brightmail-Tracker:\r
  58  H4sIAAAAAAAAA+NgFmphleLIzCtJLcpLzFFi42IR4hTV1nVI+RVs8Oy1gsWN1m5Gi+s3ZzI7\r
  59         MHk8W3WL2WPLoffMAUxRXDYpqTmZZalF+nYJXBlvP7MWzBCsuHhgClsD41PeLkZODgkBE4l/\r
  60         d64wQdhiEhfurWfrYuTiEBKYzSSxcMozRghnI6PExo9XWCGc00wSWw5chCpbwiix+mo7G0g/\r
  61         i4CqxM6Vn9lBbDYBDYnftxaDzRUBil/dNhmshllAWuLb72awuLBAlMSz9fMZQWxeAW2J948u\r
  62         Qq37xCixYMtOdoiEoMTJmU9YIJq1JG78ewnUzAE2aPk/DpAwp4CRRPP1PWDlogIqElNObmOb\r
  63         wCg0C0n3LCTdsxC6FzAyr2KUTcmt0s1NzMwpTk3WLU5OzMtLLdI118vNLNFLTSndxAgKbHYX\r
  64         lR2MzYeUDjEKcDAq8fCu5PwVLMSaWFZcmXuIUZKDSUmU900oUIgvKT+lMiOxOCO+qDQntfgQ\r
  65         owQHs5IIbzsfUI43JbGyKrUoHyYlzcGiJM771toqWEggPbEkNTs1tSC1CCYrw8GhJMErkAzU\r
  66         KFiUmp5akZaZU4KQZuLgBBnOAzT8fxLI8OKCxNzizHSI/ClGRSlxXnuQZgGQREZpHlwvLPG8\r
  67         YhQHekWY9zVIOw8wacF1vwIazAQ02LTnJ8jgkkSElFQDY8Zzi+cbCpT9KhySXYKFDBabLBPw\r
  68         /Ldxj41JzZL3IkJXv919vFN+4QKhM53PtHhE7524xc+VG+s8gWE/l9tPPTFjlZpY3SRNkahz\r
  69         KxY/Nq4Puc55/vThaHOjhZ7tKt/nHHNYsDNrKpfjiblM4tPaLuV/LV10d7GMx8UQictF7x9N\r
  70         mTM9RKH8jRJLcUaioRZzUXEiAEnPgRoXAwAA\r
  71 Cc: notmuch@notmuchmail.org\r
  72 X-BeenThere: notmuch@notmuchmail.org\r
  73 X-Mailman-Version: 2.1.13\r
  74 Precedence: list\r
  75 List-Id: "Use and development of the notmuch mail system."\r
  76         <notmuch.notmuchmail.org>\r
  77 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
  78         <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
  79 List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
  80 List-Post: <mailto:notmuch@notmuchmail.org>\r
  81 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
  82 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
  83         <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
  84 X-List-Received-Date: Sun, 24 Aug 2014 22:16:39 -0000\r
  85 \r
  86 Quoth David Bremner on Aug 23 at  8:58 pm:\r
  87 > Austin Clements <amdragon@mit.edu> writes:\r
  88 > \r
  89 > >>> @@ -1048,7 +1164,8 @@ notmuch_database_get_version (notmuch_database_t *notmuch)\r
  90 > >>>  notmuch_bool_t\r
  91 > >>>  notmuch_database_needs_upgrade (notmuch_database_t *notmuch)\r
  92 > >>>  {\r
  93 > >>> -    return notmuch->needs_upgrade;\r
  94 > >>> +    return notmuch->mode == NOTMUCH_DATABASE_MODE_READ_WRITE &&\r
  95 > >>> + (NOTMUCH_FEATURES_CURRENT & ~notmuch->features);\r
  96 > >>>  }\r
  97 > >>\r
  98 > >> Maybe I'm not thinking hard enough here, but how does this deal with a\r
  99 > >> feature that is needed to open a database in read only mode? Maybe it\r
 100 > >> needs a comment for people not as clever as Austin ;).\r
 101 > >\r
 102 > > I'm not quite sure what you mean.  notmuch_database_needs_upgrade\r
 103 > > returns false for read-only databases because you can't upgrade a\r
 104 > > read-only database.  This was true before this patch, too, though it was\r
 105 > > less obvious.  (Maybe that's not what you're asking?)\r
 106 > \r
 107 > Yes, that's what I was asking. I guess it's orthogonal to your patch\r
 108 > series, but the logic of returning FALSE for read only databases is not\r
 109 > very intuitive to me (in the sense that "needs upgrade" is not the\r
 110 > opposite of "can't be upgraded".  Your new comment later in the series\r
 111 > is better, but it would IMHO be even better if you mentioned the read\r
 112 > only case.\r
 113 \r
 114 That's a good point.  Ideally this should be\r
 115 "notmuch_database_can_upgrade" or something, which I think would\r
 116 capture exactly what it means after this series.  However, I don't\r
 117 think it's worth breaking API compatibility given that this is already\r
 118 how callers use this function (even though that violates the current\r
 119 library spec).\r
 120 \r
 121 So, how's this for a more updated doc comment on needs_upgrade?\r
 122 \r
 123 /**\r
 124  * Can the database be upgraded to a newer database version?\r
 125  *\r
 126  * If this function returns TRUE, then the caller may call\r
 127  * notmuch_database_upgrade to upgrade the database.  If the caller\r
 128  * does not upgrade an out-of-date database, then some functions may\r
 129  * fail with NOTMUCH_STATUS_UPGRADE_REQUIRED.  This always returns\r
 130  * FALSE for a read-only database because there's no way to upgrade a\r
 131  * read-only database.\r
 132  */\r