[rfc] developer documentation on user interaction

[Stephen J. Turnbull]

John Arbash Meinel writes:

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

This isn't about specific points.  That's "Special cases aren't
special enough to break the rules" (even if they have historically
done so and gotten away with it).  This is about backward
compatibility, aka "Although practicality beats purity."  Vincent
claims he understands the joke, but I don't think he does, really, and
I think you're missing it, too.

That is Alexander's issue, as I see it, and that is why I spoke up.  I
have no opinion about how the specific issues should be resolved.  I
do see a problem in communication here, because the downstream devs
and the upstream devs have very different value systems operating.
Vincent, and now you, are focusing on resolving specifics (and you
guys are going to win 90% of those), while Alexander's concern is not
how any given specific is resolved, but that there be as few specifics
to resolve as possible.  Ie, he doesn't mind if you are right more
often than not, he minds how often the discussion arises at all.

Simply discussing how to fix something that wasn't broke and hasn't
changed in one's code is very enthusiasm-draining, but you guys are
showing no sympathy.

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

Yep.  Now you're talking Alexander's language, although not in a way
that would be useful to him.

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

[Aside: I like the Python approach, which says it's *never* worth it
(at the z level of x.y.z).  If it's going to break compatibility you
document the bug and tell people "the doctor says, 'Don't do that!'"
People who need the bug fixed are going to have to move up to the next
version.  This is one of the main things that keeps XEmacs popular
vs. Emacs in the corporate world: we promise that packages we
distribute will work with 5 year old XEmacsen, and they mostly work
with 10-year-old XEmacsen, whereas in Emacs recent versions of most
packages only work properly on the as-yet unreleased dev version.]