CONTRIBUTING.rst: Add UI sectionjennis/frontend_documentation

Now that the frontend has been mostly reworked/standardized,
this patch attempts to put our some guidelines/information in
around UI contributions.

2 files changed, 77 insertions, 0 deletions

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index b99ede4c4..048136ef7 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -264,3 +264,4 @@ Further information
    hacking/grpc_protocols.rst
    hacking/managing_data_files.rst
    hacking/updating_python_deps.rst
+   hacking/ui.rst
diff --git a/doc/source/hacking/ui.rst b/doc/source/hacking/ui.rst
new file mode 100644
index 000000000..37a035df4
--- /dev/null
+++ b/doc/source/hacking/ui.rst
@@ -0,0 +1,76 @@
+Contributing to the UI
+~~~~~~~~~~~~~~~~~~~~~~
+
+As we wish to cleanly separate BuildStream's core from the frontend, anything
+user facing should be defined within the modules contained within the `_frontend
+<https://gitlab.com/BuildStream/buildstream/tree/master/src/buildstream/_frontend>`_
+directory.
+
+BuildStream's frontend includes:
+
+    * Implementation of the command line interface (cli.py)
+    * Logline/text formatting (widget.py)
+    * The main application state (app.py) which initializes the stream to handle
+      logging and user interactions.
+    * Colour profiles (profile.py)
+    * Rendering of the status bar (status.py)
+    * Autocompletion behaviour (completions.py)
+
+
+The command line interface
+''''''''''''''''''''''''''
+
+All of BuildStream's commands are defined within the module `cli.py
+<https://gitlab.com/BuildStream/buildstream/blob/master/src/buildstream/_frontend/cli.py>`_ -,
+the main entry point which implements the CLI.
+
+The command line interface is generated with `Click
+<https://palletsprojects.com/p/click/>`_ - a third party Python package. Click
+is easy to use and automatically generates help pages.
+
+When working with commands, please adhere to the following checklist:
+
+1. All commands should be defined with a help text
+2. The command should be placed within the appropriate sub group
+    - If the command manipulates sources, it should be part of the
+      :ref:`source_subcommands`.
+    - If the command manipulates cached artifacts, it should be part of the
+      :ref:`artifact_subcommands`.
+    - If the command has anything to do with workspaces, it should be part
+      of the :ref:`workspace_subcommands`.
+3. If the command is intended to work with artifact refs as well as element
+   names, the command's argument should be "artifacts" as this supports the
+   auto-completion of artifact refs.
+4. The supported `--deps` options are: "run", "build", "all", "plan" and "none".
+   These are always of type `click.Choice
+   <https://click.palletsprojects.com/en/7.x/options/#choice-options>`_ and
+   should always be specified with a default. If the default is "none", note that
+   we use the string "none", not the Python built-in ``None``. In addition to this,
+   the ``show_default`` flag should be set to ``True``.
+5. Commands should use the app and go through the stream (via a similarly named
+   method within Stream) in order to communicate to BuildStream's core.
+
+
+Displaying information
+''''''''''''''''''''''
+
+Output which we wish to display to the user from the frontend should use the
+implemented classes in widget.py. This module contains classes which represent
+widgets for displaying information to the user.
+
+To report messages back to the frontend, we use the ``Message()`` object
+which is available from the ``Context``.
+
+Supported message types are defined in `_message.py
+<https://gitlab.com/BuildStream/buildstream/blob/master/src/buildstream/_message.py>`_
+and various uses of the messenger are defined in `_messenger.py
+<https://gitlab.com/BuildStream/buildstream/blob/master/src/buildstream/_messenger.py>`_
+
+The ``Messenger`` class defines various methods which allow us to report back to
+the frontend in particular ways. The common methods are:
+
+* ``Messenger.message()`` - the central point through which all messages pass
+* ``Messenger.timed_activity()`` - a context manager for performing and logging
+  timed activities.
+* ``Messenger.simple_task()`` - a Context manager for creating a task to report
+  progress too.