[rfc] developer documentation on user interaction

[Stephen J. Turnbull]

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. 

So does git.  In the case of git it is explicitly because they are
unwilling to promise API stability, and there is a good alternative:
scripting the CLI, which is quite stable.  So there is no need for a
stable API.  I suppose the rationale for hg is similar.

 > Here bzr devs *want* bzrlib to be used.

"""
You can't always get what you want
But if you try some time
You just might find
You get what you need
"""
    -- Mick Jagger, trying to achieve an expression of Pythonic Zen

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.

 > And if I had more free time on my hands I certainly try to make
 > emacs use bzrlib instead of bzr

Interesting.  That's what Alexander said.<wink>

 >     Stephen> 2.  The audience for the CLI demands stability;
 > 
 > As in: "I don't want to test which version I'm using so don't
 > change anything there or I'm doomed" ?

The audience I'm talking about here is Russel, Ben, and Maritza, not
Alex.  And yes, I think they'd agree that they don't want to have to
do "bzr --version" on an unfamiliar host in order to know what to tell
the new dev they're mentoring how to use bzr's CLI.  Don't you agree?

 > So, I think "practicality beats purity" here, means, let's use
 > bzrlib and stop pretending using bzr is the right way to go for
 > wrong reasons ;)

No, that's not what it means.  It means "if Alexander finds bzr more
useful than bzrlib, maybe he's got a point."  Then again, even though
that's what it means, maybe he doesn't have a point, after all.  Zen
is like that.  Actually, like *this*.<wink>

Without-pretension-to-'bot-hood-ly y'rs,