Re: [Monotone-devel] interface version / command matrix

[Nuno Lucas]

On Sun, Mar 30, 2008 at 7:24 AM, Stephen Leake <address@hidden> wrote:
> Thomas Keller <address@hidden> writes:
> >> Unless the tool uses _only_ automate commands, it _must_ check the mtn
>  >> version number. I don't think automate is powerful enough for that.
>  >> Nor do I think it needs to be.
>  >
>  > That is the contract interface_version guarantees. guitone _solely_
>  > depends on automate currently (ok, despite one very little use case
>  > where I use mtn pubkey - but this is on my TODO list, i.e. I plan to
>  > implement mtn automate get_public_key some time).
>  >
>  >>> No code changes would need to be done on the client's side to
>  >>> support a new monotone release which does no or just a minor changes
>  >>> to the interface.
>  >> I define "the interface" to include the mtn commands, as well as the
>  >> mtn automate commands.
>  >
>  > For me its the other way around. I program the tool against the
>  > automation interface by purpose, because this interface is the only
>  > one which guarantees me at least some kind of stability. Sure, there
>  > are still a lot of missing commands and functionality, the problem of
>  > mediocre error (plain string) reporting, no ticker support, aso. - but
>  > this is nothing which cannot be addressed in the future.
>  >
>  > The "big" plan for me certainly is making automate feature-complete
>  > (with the exclusion of some rarely needed commands like mtn crash ;),
>  > because only when its feature-complete it can actually be useful for
>  > everybody. And people can start using it for even more obscure things,
>  > like providing new command line frontends which has already been done
>  > in the past (see the mtn_automate lua function).
>
>  That makes sense.
>
>  However, the more features the automate interface supports, the more
>  likely it is that some individual feature will suffer an incompatible
>  change, and the major version will increase, incorrectly labeling all
>  features as incompatible.
>
>  So a keyword list is the right way to go.

And what about the ugly (but which we don't care as automate isn't for
human consumption) way of just adding version numbers to the command
name itself?

For example, suppose we add an "--xml" option to "mtn automate keys".
As the output of the command will always be backward compatible using
any other older option, we can just check if the "--xml" option is
supported by checking the return error or an error output (which by
the way, seems to be missing -- something easy to parse like "401
Unknown option").

If in a latter version we need to change the output to something not
backward compatible (like UN deciding the world should all switch to
Unicode output), just add a "mtn automate keys_v2", and recent clients
will now about it and use it instead of the old interface.

May seem ugly, but it's simple and easy for clients to use and know
what they can expect.

At some time we can decide to drop back compatibility (like monotone
v2.0 is released and we want to get the garbage out), but we can
specify that between major version numbers we keep backward
compatibility, not when it changes. Clients are used to this using
shared libraries, anyway.

What seems to be lacking is a way for clients to know a command isn't
implemented when using automate on a pipe (as they can't check the
return error code). I never used automate on a pipe so don't know how
any error checking  is done right now.


My 2 € cents,
~Nuno Lucas