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

[Timothy Brownawell]

Thomas Keller wrote:
> 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`.

The ignorable stuff is all on stderr, this would be on stdout like the
rest of the actual interesting output (stdio packets). And the "without
using the format already" is why it would be something simple like a
leading <number> <whitespace> rather than a full stdio packet.

>> (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.)

The whole idea of stdio is to not need to make multiple calls, so I'd
think it makes sense to make sure any necessary versioning information
is included instead of needing to be obtained separately.

>> 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.

I'd think the version number could be put as an argument to
CMD_AUTOMATE(), and then command_version would know how to look that up.

The comments above the code are basically redundant with what's in
monotone.texi and can probably be dropped.

Having the individual commands versioned separately ought to make
maintaining the compatibility matrix easier, since it could be scripted
(spin through "mtn help automate" output, call command_version on each
item with both old and new monotones).

> 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.

Maybe we should drop interface_version (well, just stop incrementing it
after a last major version change; the command itself would have to stay
there). The "supports" idea maps very well to having a "command_version"
that returns, say, -1, for nonexistent commands, and this would make
interface_version rather redundant.

>> 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
>