summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJames Ennis <james.ennis@codethink.co.uk>2019-09-04 13:01:58 +0100
committerTristan Maat <tristan.maat@codethink.co.uk>2019-09-16 13:11:09 +0100
commit163a4758cfdf1c72e300fc86302a2c3da5bb17be (patch)
treed278df67657b91a2fdafc99e24645da5bebe5460
parent4d9b595da63c24b3b5251cce47f23b2ee6cfd86b (diff)
downloadbuildstream-163a4758cfdf1c72e300fc86302a2c3da5bb17be.tar.gz
CONTRIBUTING.rst: Add UI section
Now that the frontend has been mostly reworked/standardized, this patch attempts to put our some guidelines/information in around UI contributions.
-rw-r--r--CONTRIBUTING.rst1
-rw-r--r--doc/source/hacking/ui.rst78
2 files changed, 79 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..e37dda43b
--- /dev/null
+++ b/doc/source/hacking/ui.rst
@@ -0,0 +1,78 @@
+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.