4a/77714a5e451a96e95b9774788caef203a90260

   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 A8CCA431FAE\r
   6         for <notmuch@notmuchmail.org>; Tue, 29 Jul 2014 09:48:59 -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 A0LqXMlR2Izp for <notmuch@notmuchmail.org>;\r
  16         Tue, 29 Jul 2014 09:48:54 -0700 (PDT)\r
  17 Received: from dmz-mailsec-scanner-2.mit.edu (dmz-mailsec-scanner-2.mit.edu\r
  18         [18.9.25.13])\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 A8069431FD5\r
  22         for <notmuch@notmuchmail.org>; Tue, 29 Jul 2014 09:48:23 -0700 (PDT)\r
  23 X-AuditID: 1209190d-f79c06d000002f07-87-53d7d057ad7b\r
  24 Received: from mailhub-auth-1.mit.edu ( [18.9.21.35])\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-2.mit.edu (Symantec Messaging Gateway) with SMTP\r
  28         id 2C.0D.12039.750D7D35; Tue, 29 Jul 2014 12:48:23 -0400 (EDT)\r
  29 Received: from outgoing.mit.edu (outgoing-auth-1.mit.edu [18.9.28.11])\r
  30         by mailhub-auth-1.mit.edu (8.13.8/8.9.2) with ESMTP id s6TGmMHg003485; \r
  31         Tue, 29 Jul 2014 12:48:22 -0400\r
  32 Received: from drake.dyndns.org (31-33-71.wireless.csail.mit.edu\r
  33         [128.31.33.71]) (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 s6TGmFph030276\r
  36         (version=TLSv1/SSLv3 cipher=AES256-SHA bits=256 verify=NOT);\r
  37         Tue, 29 Jul 2014 12:48:21 -0400\r
  38 Received: from amthrax by drake.dyndns.org with local (Exim 4.77)\r
  39         (envelope-from <amdragon@mit.edu>)\r
  40         id 1XCAZT-0007HD-2K; Tue, 29 Jul 2014 12:48:15 -0400\r
  41 From: Austin Clements <amdragon@MIT.EDU>\r
  42 To: notmuch@notmuchmail.org\r
  43 Subject: [PATCH v2 14/14] lib: Update doc of notmuch_database_{needs_upgrade,\r
  44         upgrade}\r
  45 Date: Tue, 29 Jul 2014 12:48:12 -0400\r
  46 Message-Id: <1406652492-27803-15-git-send-email-amdragon@mit.edu>\r
  47 X-Mailer: git-send-email 2.0.0\r
  48 In-Reply-To: <1406652492-27803-1-git-send-email-amdragon@mit.edu>\r
  49 References: <1406652492-27803-1-git-send-email-amdragon@mit.edu>\r
  50 X-Brightmail-Tracker:\r
  51  H4sIAAAAAAAAA+NgFtrNIsWRmVeSWpSXmKPExsUixCmqrBt+4XqwQe8DeYvVc3ksrt+cyezA\r
  52         5LFz1l12j2erbjEHMEVx2aSk5mSWpRbp2yVwZVz9/4utYL9AxeXm2ywNjAd4uxg5OSQETCQW\r
  53         7lrDDGGLSVy4t56ti5GLQ0hgNpPE/bY1rCAJIYGNjBLTNkRDJI4xSZz//JcFIjGXUWJLUwqI\r
  54         zSagIbFt/3JGEFtEQFpi593ZYM3MAo4Sn/cvYgOxhQVCJVr+rwWrYRFQleiYfBtsMy9QzZ5b\r
  55         91ghrpCTaLjxCayeEyh+695dJohdDhKHZm1mmcDIv4CRYRWjbEpulW5uYmZOcWqybnFyYl5e\r
  56         apGukV5uZoleakrpJkZwGEny7mB8d1DpEKMAB6MSDy/HgmvBQqyJZcWVuYcYJTmYlER59fZd\r
  57         DxbiS8pPqcxILM6ILyrNSS0+xCjBwawkwst3FijHm5JYWZValA+TkuZgURLnfWttFSwkkJ5Y\r
  58         kpqdmlqQWgSTleHgUJLgXXseqFGwKDU9tSItM6cEIc3EwQkynAdo+D6QGt7igsTc4sx0iPwp\r
  59         RkUpcd7sc0AJAZBERmkeXC8szl8xigO9IszbBtLOA0wRcN2vgAYzAQ1mdQEbXJKIkJJqYKws\r
  60         KA/MTOm7lPzjXsGW8sTztUwZtU8sTsqxZNzzbfEtSwrI2F/C4s/0KueHrcAPtepQJjWf7Cbu\r
  61         V78sfPTPpbnMLOF4YLzIxSfkzYPY7zuYXA9ve5n74rP+drmFR1dHdJxY9NjQ9eKu6v8FieLt\r
  62         Ky/41pTevTnnh1uw6VGWh/bOxm/bWN9eVWIpzkg01GIuKk4EAC6sQn/OAgAA\r
  63 X-BeenThere: notmuch@notmuchmail.org\r
  64 X-Mailman-Version: 2.1.13\r
  65 Precedence: list\r
  66 List-Id: "Use and development of the notmuch mail system."\r
  67         <notmuch.notmuchmail.org>\r
  68 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
  69         <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
  70 List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
  71 List-Post: <mailto:notmuch@notmuchmail.org>\r
  72 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
  73 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
  74         <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
  75 X-List-Received-Date: Tue, 29 Jul 2014 16:48:59 -0000\r
  76 \r
  77 Clients are no longer required to call these functions after opening a\r
  78 database in read/write mode (which is good, because almost none of\r
  79 them do!).\r
  80 ---\r
  81  lib/notmuch.h | 21 ++++++++++++---------\r
  82  1 file changed, 12 insertions(+), 9 deletions(-)\r
  83 \r
  84 diff --git a/lib/notmuch.h b/lib/notmuch.h\r
  85 index cbf2ba5..d771eb2 100644\r
  86 --- a/lib/notmuch.h\r
  87 +++ b/lib/notmuch.h\r
  88 @@ -352,22 +352,25 @@ unsigned int\r
  89  notmuch_database_get_version (notmuch_database_t *database);\r
  90  \r
  91  /**\r
  92 - * Does this database need to be upgraded before writing to it?\r
  93 + * Is the database behind the latest supported database version?\r
  94   *\r
  95 - * If this function returns TRUE then no functions that modify the\r
  96 - * database (notmuch_database_add_message, notmuch_message_add_tag,\r
  97 - * notmuch_directory_set_mtime, etc.) will work unless the function\r
  98 - * notmuch_database_upgrade is called successfully first.\r
  99 + * If this function returns TRUE, then the caller may call\r
 100 + * notmuch_database_upgrade to upgrade the database.  If the caller\r
 101 + * does not upgrade an out-of-date database, then some functions may\r
 102 + * fail with NOTMUCH_STATUS_UPGRADE_REQUIRED.\r
 103   */\r
 104  notmuch_bool_t\r
 105  notmuch_database_needs_upgrade (notmuch_database_t *database);\r
 106  \r
 107  /**\r
 108 - * Upgrade the current database.\r
 109 + * Upgrade the current database to the latest supported version.\r
 110   *\r
 111 - * After opening a database in read-write mode, the client should\r
 112 - * check if an upgrade is needed (notmuch_database_needs_upgrade) and\r
 113 - * if so, upgrade with this function before making any modifications.\r
 114 + * This ensures that all current notmuch functionality will be\r
 115 + * available on the database.  After opening a database in read-write\r
 116 + * mode, it is recommended that clients check if an upgrade is needed\r
 117 + * (notmuch_database_needs_upgrade) and if so, upgrade with this\r
 118 + * function before making any modifications.  If\r
 119 + * notmuch_database_needs_upgrade returns FALSE, this will be a no-op.\r
 120   *\r
 121   * The optional progress_notify callback can be used by the caller to\r
 122   * provide progress indication to the user. If non-NULL it will be\r
 123 -- \r
 124 2.0.0\r
 125 \r