on interface stability (was Re: [Monotone-devel] renaming monotone executable (again))

[Nathaniel Smith]

On Mon, Feb 27, 2006 at 01:04:15AM -0500, Yury Polyanskiy wrote:
> On Sun, 2006-02-26 at 04:15 -0800, Nathaniel Smith wrote:
> >   -- Having a single, standard abbrev is very useful.  If, for
> >      instance, we switch the command name to "mtn", we should also (I
> >      suggest):
> >        -- make the bookkeeping directory MTN (instead of MT)
> >        -- make the ignore file .mtn-ignore (instead of .mt-ignore)
> 
> OMG, if you count votes then please don't change these (and .mt-attrs). 

.mt-attrs no longer exists.  Attrs have moved to the manifest, and
'rosterify' removes the .mt-attrs file and creates the appropriate
attrs directly as it goes.

> This doesn't seem really crucial but is going to ruin many scripts (and
> contribute to the perception that 'monotone changes too often').
> 
> Examples? Well:
>  a) "checkout-crlf-copy" (monotone --rcfile=crlf.rc co ...; cp crlf.rc
> target-dir/MT/monotonerc).
>  b) "import dir as a revision" (cp -r working-copy/MT import-dir/;
> monotone drop --missing; monotone add --unknown);

Won't renaming the executable at all also break these scripts?

> Not that these are hard to change but I think this has been copied all
> over the place and will be pretty annoying to correct (especially when
> scripts are part of the sources etc, etc.).

Right; changes suck.  The ultimate goal is to never break anything
ever.  The question is: do we change now and deal with the pain (and
noting that 0.26 already breaks many many scripts) so that we
eventually have something clean and consistent to freeze; or, do we
just live with inconsistency forever?

Historically, we have come down emphatically on the "change
aggressively now, worry about compatibility later" side of the scale.
For a project as ambitious as monotone, this was basically a
necessity.  Just imagine if we had frozen after a year of development
-- we wouldn't even have revisions at all!  Or even after 2.5 years --
we would be stuck with a slow, broken, and incomplete history
representation.

It's only in the last few months that we've finally learned enough
about the problem space to have some confidence that we know what a
full, dependable solution should look like.  The new roster-style
revision and manifest formats are _the_ first thing about monotone
where I am willing to -- tentatively! -- say "yeah, this won't change
again between now and 1.0".  We're just now reaching the point where
we can start seeing 1.0 over the horizon, and how we might get there.

I definitely want to get to 1.0.  The changes I proposed upthread are
definitely intended to get the affected pieces into a state that we
are comfortable keeping forever.  (Though, no guarantees yet -- we've
been hit by unexpected new facts too often to make those without _at
the minimum_ some months of real-world experience with a change...)

If we freeze now, we'll be stuck with a clunky UI, broken trust and
key management functionality, a non-extendable protocol, etc.  We can
fix all these things, we basically know how to fix all these things,
but compatibility is going to have to be broken at various places, and
we have a finite amount of time to budget between smoother transitions
and making actual improvements.

Overall, we take compatibility and stability _very_ seriously.  That
means that we aren't going to declare 1.0 until we have a _very_ high
degree of confidence that what we have at that point is solid and
flexible enough that we _can_ stick with it.  And, paradoxically, that
means we had better break some stuff now, while we can still mostly
get away with it...

Anyway, that's where I'm coming from on the issue, anyway.  Does this
make sense?  Does reading it make you nod your head and go off to
update your scripts with a smile on your face and enthusiasm in your
heart? :-)  Obviously, as we gain more users, changes are becoming
higher cost, and I'm not confident I have a good sense of what the
appropriate trade-off is.  As rules of thumb, pain from making a given
change will only go up over time, so one should change sooner rather
than later; and pain from making a change is finite and passes, while
pain from keeping a clunky or broken interface goes to infinity as one
integrates over time.  But we've also burned users by doing this (in
particular, OpenEmbedded's problems, and your complaint, among
others), so perhaps we should spend more time making migration
smoother.  Hopefully this email will help make clear why we do
the things we do and set some expectations for what is likely to
happen in the future... and also elicit responses from people about
how much breakage is reasonable :-).

Do you feel like this email is something you can point people at if
they complain that monotone changes too often?  Do you feel like this
amount of change is reasonable?

Cheers,
-- Nathaniel

P.S.: in case this email does become a standard thing to refer people
to, I should point out that in the subject, "again" refers to the
_discussion_ coming up again; we don't rename the executable every
week or anything :-).  In fact we've never done it at all...