Re: [Monotone-devel] review of nvm.automate_out_of_band

[Thomas Keller]

Am 27.11.09 18:14, schrieb Timothy Brownawell:
> Thomas Keller wrote:
>> Am 22.11.09 20:26, schrieb Thomas Keller:
>>>> [...]
>> What do you think?
> 
> I like it and it really does make more sense, the only issue is if
> interface_version is being checked through stdio instead of as a
> standalone command. Probably stdio/remote_stdio should start by
> outputting <stdio-version> <whitespace> in case we eventually change the
> stdio format again 

This is problematic because it would introduce "out-of-band" content /
chatter which we tell the user now that he can completly ignore (like
f.e. the netsync P() messages on remote_stdio connect). And of course
its a chicken-egg problem - we don't really want to allow any meaningful
non-stdio output and cannot tell the user the format's version without
using the format already. I'd probably vote for telling people to use
`au interface_version` directly w/o stdio and for not introducing yet
another (magic) versioning number. After all we can even return this
remotely with `au remote interface_version`, so it isn't even an issue
for `remote_stdio`.

> (not interface_version, something specific to stdio.
> interface_version changes when even some command you don't care at all
> about changes formats. 

The contract the interface_version numbering gives to the user is
straight forward in this case however:

1) if the minor version changes, _everything_ in the old version should
still work as expected, plus some new stuff

2) if the major version changes, _anything_ which worked in the old
version could now be broken

Since stdio itself is part of the automate command subset, its enough to
raise the major version for this change. Of course we don't leave the
user alone with 2), I've compiled and managed a good overview of the
changes which came with an interface_version change for a couple of time
now here and I plan to continue taking care of that matrix [0].

Maybe we should just make two missing assumption hard facts now and
document them properly:

1) The command "automate interface_version" must never change its output
format.

2) Implementors of the "automate" interface should always call "automate
interface_version" in a non-stdio context, because the format of stdio
might be different.

(We could go so far and make interface_version a CMD_AUTOMATE_NO_STDIO,
but since this hasn't been the case in the past, I wouldn't go so far.)

> we also need a "command_version command ..." that
> can list versions (including "does not exist") of specific automate
> commands, which is entirely unrelated to this discussion except that
> what it would print for "command_version stdio" is what I'm thinking
> stdio should start with.). 

Nice in theory, but impractical, because we'd now not have to take care
about a single versioning, but multiple ones, one for every command.
This is already bad enough now, since we basically document everything
in three places, monotone.texi, the code comment above the actual
implementation and the interface version matrix I mentioned before. So
whatever new we come up with should be self-describing, machine-readable
and maybe even interface-complete (i.e. not only for a single command)
at the same time to make all three places where we document stuff right
now obsolete.

Wrt "feature" versioning, I also like what Tony Cooper did for the Perl
implementation of Monotone::AutomateStdio [0] (scroll down to
`$mtn->supports($feature)`); he gives certain features symbolic names
and makes those queryable over the interface. But I'm not sure how to
map this properly on monotone itself without dumping the idea of
interface_version completly.

> That way if we change the format again,
> frontends won't have to call interface_version separately and will be
> able to give better error messages ("please upgrade") than just failing
> to parse the output when they don't call it separately.

In theory checking the interface_version should already be enough, but
you're right: if a program could simply continue to work if it does not
use any of the (incompatibly) changed commands.

Thomas.

[0] http://monotone.ca/wiki/AutomateVersions/
[1] http://search.cpan.org/perldoc?Monotone::AutomateStdio

-- 
GPG-Key 0x160D1092 | address@hidden | http://thomaskeller.biz
Please note that according to the EU law on data retention, information
on every electronic information exchange might be retained for a period
of six months or longer: http://www.vorratsdatenspeicherung.de/?lang=en

signature.asc
Description: OpenPGP digital signature