Re: [Monotone-devel] New commands (for mtn, in lua)

[Nathaniel Smith]

On Tue, Sep 04, 2007 at 08:49:32PM -0600, Derek Scherger wrote:
> Nathaniel Smith wrote:
> > The requirement for landing a new automate command in mainline is that
> > the semantics (what it does) and interface (how you tell it what to do
> > and how it tells you what its done) must be fully documented and
> > tested.  Also, we should be willing to keep those semantics and
> > interface fixed going forward.  Having automate access to the
> 
> While this seems to work well enough for "simple" things I think it
> makes doing more complicated things overly scary. More complicated
> things are difficult to get right the first time so people either don't
> do them or we end up keeping broken things around rather than fixing
> them for the sake of stability.

Agreed.  To tell the truth, I don't actually think we should care that
much about breaking automate interfaces right now.  What we should
care about is that every time we add something to automate, or change
something that's already there, we are getting *closer* to an
interface that we can live with permanently.

Writing exhaustive documentation is how you discover that your
semantics are too complicated, because they take three paragraphs to
explain.  Writing exhaustive tests is how you discover that you forgot
to decide what should happen in some weird corner case -- and also,
incidentally, how you know that the code works at all, since untested
code *always* changes its behavior sooner or later.  So if we're not
writing docs and tests, then who knows, we may be moving backwards or
churning in place rather than actually improving things.  And,
fortunately, whether we write docs and tests is something we can
easily control!

> It would be nice if we could somehow say "this is here in automate land
> but is still experimental and may change." Could we simply add a
> stable/unstable status to the interface documentation or some sort of
> deprecation indicator that says "this old automate command is going to
> go away in version x.yy" or something?

Then, yeah, sometimes you do the best you can and aren't sure whether
the result is good or not, maybe there should be some way to mark
interfaces that we hope are stable but aren't really sure about.  I
think at some point I suggested having another command that was like
automate, but also included unstable interfaces -- so you use
'automate' if you only want stable stuff, and 'betamate' if you're
okay with unstable stuff too, or whatever.  In practice, I'm not sure
what good this would do.  It's not like someone can say "Oh, inventory
is unstable, I'll just get the status of the files in the tree some
other way", since there is no other way; everyone will just end up
using the unstable interfaces anyway.  And if it turns out that
something we did promote to automate is broken, well, we have to fix
broken things even if they do have a version number on them...

Also, in a small volunteer project like this, we can't put useful
schedules on when new things will be written or old things will be
removed.  In practice I doubt people would remember to remove the
"unstable" marker on interfaces -- if they even had any way to know
when they should.

So my suggestion:
  -- just put things that are intended for programs in automate
  -- but only after you've made the effort to make them good.
     "Effort" includes doing the things you have control over (like
     thinking hard, and writing docs and tests), but not the ones you
     don't (if you're getting paralyzed because you need more data and
     it's impossible to get that data, then skip it)
  -- and if experience later shows that they weren't so good after
     all, oh well, just fix them

> Yes, sadly, I'm still bearing the scars of automate inventory. ;)
> 
> I would really like to see the new version of inventory merged at some
> point, however I'm also still not entirely convinced that's exactly what
> we want. Personally I think I liked the node id's in the format for
> example but I haven't been all that directly involved lately so who am I
> to say.

Yeah, it'd be nice if the people who actually cared about inventory
(e.g. the guys working on frontends like guitone and tracmtn and
monoclipse and all) could just pick one they could all live with and
went with it.

-- Nathaniel

-- 
The Universe may  /  Be as large as they say
But it wouldn't be missed  /  If it didn't exist.
  -- Piet Hein