Re: [PATCH 00/10] CLI output versioning

From: Austin Clements <amdragon@MIT.EDU>
To: Mark Walters <markwalters1009@gmail.com>
Cc: notmuch@notmuchmail.org
Subject: Re: [PATCH 00/10] CLI output versioning
Date: Wed, 12 Dec 2012 20:46:17 -0500	[thread overview]
Message-ID: <20121213014617.GD6187@mit.edu> (raw)
In-Reply-To: <878v98hoyp.fsf@qmul.ac.uk>

Quoth Mark Walters on Dec 08 at  9:29 am:
> 
> Hi
> 
> Overall this series looks good. As we discussed on irc I think i would
> prefer global NOTMUCH_SCHEMA_MIN as I am a little worried about these
> proliferating (eg if someone decides text output also needs versioning
> etc) In addition, if we do find the distinction useful it would be easy
> to add at a later date.

Will do.

> One tiny comment on the manpage updates: now that you mention two return
> values explicitly should the other possibilities be mentioned too or are
> they so obvious it is not needed?

I thought about this, but couldn't figure out what to say for exit
status 1 other than "Unspecified error".  Hence I carefully worded the
man page to say *special* exit status codes.

> Would it be worth having some emacs test for the error handling? (eg set
> notmuch-command to something giving some stderr and an error) Inherently
> these code paths won't be tested much so I think tests could be
> particularly useful.

Good idea.

> Best wishes
> 
> Mark
> 
> 
> 
> 
> 
> 
> On Mon, 03 Dec 2012, Austin Clements <amdragon@MIT.EDU> wrote:
> > (Sorry; I forgot to include a cover letter.)
> >
> > This series is intended to help with our long-standing output format
> > versioning issue.  While the JSON format is amenable to extension,
> > there's still a high barrier to extensions because of the need to
> > support them going forward, and an even higher barrier to modifications
> > that break backwards compatibility.  Versioning will make the format
> > more dynamic, enabling us to easily improve and iterate on it.  It will
> > also address the slew of confusing bugs that people encounter when they
> > use a mismatched CLI and front-end.
> >
> > On IRC we've talking about adding version information to the output
> > format itself.  This series takes a different and, I think, better
> > approach: callers request a specific output format version on the
> > command line.  This allows notmuch to remain backwards compatible with
> > older format versions when it's easy or necessary.  This also doesn't
> > require shoehorning a version number into the output, which would be
> > awkward for both the CLI and the consumer.
> >
> > I called the argument --use-schema, but I'm open to other suggestions.
> > --use-schema is technically accurate, but perhaps not as self-describing
> > as something like --schema-version or --format-version (to parallel
> > --format).
> > _______________________________________________
> > notmuch mailing list
> > notmuch@notmuchmail.org
> > http://notmuchmail.org/mailman/listinfo/notmuch

-- 
Austin Clements                                      MIT/'06/PhD/CSAIL
amdragon@mit.edu                           http://web.mit.edu/amdragon
       Somewhere in the dream we call reality you will find me,
              searching for the reality we call dreams.