[rfc] developer documentation on user interaction

[John Arbash Meinel]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Stephen J. Turnbull wrote:
> Vincent Ladeuil writes:
> 
>  >     Stephen> 1.  Other tools such as git and hg show similar
>  >     Stephen> behavior.  It is far easier and more maintainable to
>  >     Stephen> script them than it is to use the internal APIs.
>  > 
>  > Hmm, last I heard hg strongly discourage using its internal API. 

...

> Anyway....  I read Alexander as saying that bzrlib is not very usable
> for him, for a couple of reasons, including instability of the
> interface.  I'm just pointing out that it is quite possibly true that
> the bzr CLI is more stable and therefore programs using it are more
> maintainable.
> 

So the specific point he brought up was that annotate started failing
because they weren't locking their object. However, they *should* have
been locking it before, it just wasn't an error not to. And starting to
lock it now is 100% compatible with older versions of bzrlib.

(The main effect is that if you maintain the lock, we get to maintain
more state. We've had performance issues with code not taking an
explicit lock, and assuming the implicit locks are good enough, and then
we thrash the state because we end up taking 30 locks where we should
have taken 1. So we've been moving away from implicit locking, because
the performance versus ease-of-use wasn't where we wanted to be.)


That said, our internal stability has been a bit of an up and down. For
example, I've often twisted myself in knots trying to find a way to do
something in a backwards compatible manner for something fairly trivial
that probably won't effect anyone. And then Robert redesigns
VersionedFile => VersionedFiles and breaks everyone anyway. Which meant
that we had the worst of both worlds. Spending a lot of effort trying to
maintain trivial things in backwards compatible manners, but then
realizing that we need to do a major overhaul somewhere and breaking
everything.

Which is part of Martin's desire to split off a stable versus dev. So in
2.0.x we do bug fixes, etc that we try to keep as minimally invasive as
possible. If it is going to break compatibility then it has to *really*
be worth it. And we can put compatibility breaks into the dev version,
and not try quite so hard for things that aren't worth it.

John
=:->

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (Cygwin)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAkq84OUACgkQJdeBCYSNAANwrwCgrlqShMuQqHvDL4IdfsQ76DJ1
YwQAn2RGPI3nEXiMrPWXYpWxGgVqQLxb
=pQ/c
-----END PGP SIGNATURE-----