[rfc] developer documentation on user interaction

[Martin Pool]

I was doing some cleanups to improve testability of ui (shaving yaks a
bit) and wanted to describe how bzrlib core is meant to interact with
the user, and how it could work better.  I propose to commit this
short document to the developer guide, but I'd also like wider
feedback on

- whether it should cover anything else about how we work now
(obviously it's not exhaustive)
- whether we should aim for something different in the future

-- 
Martin <http://launchpad.net/~mbp/>
-------------- next part --------------
************************************
Bazaar User Interaction Architecture
************************************

Bazaar aims to provide a library that can be mated to various text and
graphical user interfaces, and that can be used when there is no user to
interact with.  This document describes some patterns and standards to
abstract this.  It's a work in progress and not all code follows this
standard yet.

Most interaction with the user goes through a ``UIFactory`` subclass bound
to the global variable ``bzrlib.ui.ui_factory``.  Through this you can
display messages and ask for input.  Data between the UIFactory and the
rest of the library should generally be Unicode, with the UIFactory
responsible for any encoding.

Some UIFactories support only a subset of operations: for example
non-interactive UIs may refuse to ask for input.

Plugin UIFactories might choose to subclass ``TextUIFactory`` rather than
the base UIFactory.  Then if they don't have an implementation for a
particular method, it'll be done through text interaction in their
terminal window (if any) rather than giving an error.

In general we want to add more semantic methods to the UIFactory so that
non-text user interfaces can do more than just present the text that would
have been shown in the console.

Some commands are defined to send output to stdout, and want to do this
regardless of the user interface, diff being a case in point.

We're moving towards a complete API separation between developer-oriented
debug messages, recorded using ``mutter``, and user-oriented messages.
The former can still be recorded even in graphical or non-interactive
programs.

Core library code has the option to synchronously show messages to the
user or to ask for input through eg ``get_boolean`` or ``show_message``,
but it should do this with care.  In a GUI the user should be driving the
interaction, not the application.

Some core library code, such as upgrade or checkout, does some work that
should be reported to the user in a text-mode application, but that might
be shown very differently or not at all in other cases.  Rather than
repeatedly showing messages.

A particular case of this is the ProgressTask api, where a model/view
separation is fairly complete.  Core code obtains a ``ProgressTask`` from
``ui.ui_factory.nested_progress_bar``, and then feeds it events to tell
how the task is progressing, with no concern for whether or how this is
displayed to the user.