[PATCH 0/3] Sync devel/schemata with code

[PATCH 0/3] Sync devel/schemata with code

[Austin Clements]

There were some recent changes to the JSON format without accompanying
schema documentation changes [1, 2].  Though, curiously, [1] was
documented in the schema long before it was implemented owing to a
historical twist (we *used* to have Bcc in the JSON output and then it
got lost [my fault, most likely]).  Patches 2 and 3 try to increase
the visibility of the documentation; I'm open to better ways to do
this.

[1] id:7b1848a5828820912e3f7b960528b0dbc6a8b361.1347258748.git.mina86@mina86.com
[2] id:1351591967-17438-2-git-send-email-novalazy@gmail.com

[PATCH 1/3] devel: Add Reply-to to the schemata

[Austin Clements]

The code got out of sync with the documentation in 7d3c06dc.
---
 devel/schemata |    1 +
 1 file changed, 1 insertion(+)

diff --git a/devel/schemata b/devel/schemata
index 9cb25f5..e44da71 100644
--- a/devel/schemata
+++ b/devel/schemata
@@ -79,6 +79,7 @@ headers = {
     To?:            string,
     Cc?:            string,
     Bcc?:           string,
+    Reply-To?:      string,
     Date:           string
 }
 
-- 
1.7.10

Re: [PATCH 1/3] devel: Add Reply-to to the schemata

[David Bremner]

Austin Clements <amdragon@MIT.EDU> writes:

> The code got out of sync with the documentation in 7d3c06dc.

Series pushed.

d

[PATCH 2/3] show: More aggressively document the presence of devel/schemata

[Austin Clements]

Previously, the only mention of devel/schemata was a comment at the
top of format_part_json, but the JSON output code is spread across
several functions that are distributed across notmuch-show.c.  Add
references from the other three key JSON output functions.
---
 notmuch-show.c |    9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/notmuch-show.c b/notmuch-show.c
index f758f56..2fa2292 100644
--- a/notmuch-show.c
+++ b/notmuch-show.c
@@ -110,6 +110,9 @@ _get_one_line_summary (const void *ctx, notmuch_message_t *message)
 static void
 format_message_json (sprinter_t *sp, notmuch_message_t *message)
 {
+    /* Any changes to the JSON format should be reflected in the file
+     * devel/schemata. */
+
     void *local = talloc_new (NULL);
     notmuch_tags_t *tags;
     time_t date;
@@ -208,6 +211,9 @@ void
 format_headers_json (sprinter_t *sp, GMimeMessage *message,
 		     notmuch_bool_t reply)
 {
+    /* Any changes to the JSON format should be reflected in the file
+     * devel/schemata. */
+
     InternetAddressList *recipients;
     const char *recipients_string;
     const char *reply_to_string;
@@ -359,6 +365,9 @@ signer_status_to_string (GMimeSignerStatus x)
 static void
 format_part_sigstatus_json (sprinter_t *sp, mime_node_t *node)
 {
+    /* Any changes to the JSON format should be reflected in the file
+     * devel/schemata. */
+
     GMimeSignatureList *siglist = node->sig_list;
 
     sp->begin_list (sp);
-- 
1.7.10

[PATCH 3/3] devel: Document schemata in STYLE

[Austin Clements]

---
 devel/STYLE |    6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/devel/STYLE b/devel/STYLE
index 094f71d..0792ba1 100644
--- a/devel/STYLE
+++ b/devel/STYLE
@@ -73,6 +73,12 @@ Naming
   struct has a tag, it should be the same as the typedef name, minus
   the trailing _t.
 
+CLI conventions
+---------------
+
+* Any changes to the JSON output format of search or show need an
+  accompanying change to devel/schemata.
+
 libnotmuch conventions
 ----------------------------------
 
-- 
1.7.10

Re: [PATCH 0/3] Sync devel/schemata with code

[Tomi Ollila]

On Wed, Nov 07 2012, Austin Clements <amdragon@MIT.EDU> wrote:

> There were some recent changes to the JSON format without accompanying
> schema documentation changes [1, 2].  Though, curiously, [1] was
> documented in the schema long before it was implemented owing to a
> historical twist (we *used* to have Bcc in the JSON output and then it
> got lost [my fault, most likely]).  Patches 2 and 3 try to increase
> the visibility of the documentation; I'm open to better ways to do
> this.

Fine by me.

+1

Tomi