[rfc] developer documentation on user interaction

[Vincent Ladeuil]

>>>>> "Stephen" == Stephen J Turnbull <stephen at xemacs.org> writes:

    Stephen> Vincent Ladeuil writes:
    >> Adding command line options because some GUI tool need them
    >> doesn't seem like the best way to make a nice and clean CLI.

    Stephen> The problem is, as Alexander says, that the CLI is
    Stephen> *much* more stable than the API.  *In hindsight*, I
    Stephen> am not at all surprised.

That's precisely the assumption I'm challenging here.

I don't have enough qbzr coding experience to speak, but based on
my bzr-gtk and bzr/bzrlib experience, I didn't see that much
changes in neither bzr nor bzrlib nor bzr-gtk that required
*more* work because bzrlib was used instead of bzr (the notable
exception being the new progress bars whose design was changed to
better address GUI needs, by the way).

The qbzr devs may argue that bzr-gtk does less than qbzr though...

    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. 

Here bzr devs *want* bzrlib to be used.

Alexander mentioned having troubles separating stderr from stdout
when using subprocess (I don't see why but without looking at the
code I trust him), using a dedicated wrapper that can control
sys.stdout and sys.stderr and all other facets of the UIFactory
and from there calling bzrlib leave little place for such
troubles.

And given the amount of DWIM that are present and likely to be
added (and rightly so) to the CLI, my own experience in writing
wrappers strongly suggest that bzrlib is the way to go[1]. 

And one *major* reason is that the bzr devs are committed to help
bzrlib users.

And if I had more free time on my hands I certainly try to make
emacs use bzrlib instead of bzr if only because an *editor* needs
file-oriented access while our cli is tree-oriented (I digress
but that's another strong example than bzrlib can address usages
than bzr (the CLI) does not have to address).

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

    Stephen> the audience for the API demands features.

    Stephen> I think "Although practicality beats purity"
    Stephen> applies.

But here, on of my arguments is that both qbzr and bzr-gtk try to
maintain *one* source base to run against several versions of
bzr, while it may be *less* effort to only support the last or
the most recent bzr versions.

Since bzr and the associated plugins are generally packaged
together, what I'm asking here is: who cares that qbzr and
bzr-gtk are maintaining compatibility with older bzr versions ?

And speaking of bzr-gtk is the long list of supported versions
really accurate ? Does it really support 1.6.0 ? Who tried last ?

And what bzr version does qbzr support ? And who use what ?

Don't get me wrong either, I do care a lot about compatibility, I
just want to understand if we are talking about theory or
practice here.

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

       Vincent

[1]: Disclaimer: I'm expressing opinions here not telling people
     how they should write their code in their free time. Feel
     free to ignore me ;)