CONTRIBUTING.rst

@@ -142,13 +142,67 @@ their containing *package*, as such; modules which are entirely private to
 BuildGrid are named as such, e.g. ``_roy.py``.
 
 
+.. _codebase-testing:
+
+Testing
+-------
+
+BuildGrid is using ``pytest``_ for regression and newly added code testing. The
+test suite contains a serie of unit-tests and also run linting tools in order to
+detect coding-style_ breakage. The full test suite is automatically executed by
+GitLab CI system for every push to the server. Passing all the tests is a
+mandatory requirement for any merge request to the trunk.
+
+.. _pytest: https://docs.pytest.org
+
+
+Running tests
+~~~~~~~~~~~~~
+
+In order to run the entire test suite, simply run:
+
+.. code-block:: sh
+
+   python3 setup.py test
+
+You can use the ``--addopt`` function to feed arguments to pytest. For example,
+if you want to see the ``stdout`` and ``stderr`` generated y the test, run:
+
+.. code-block:: sh
+
+   python3 setup.py test  --addopts -s
+
+If you want run a  specific test instead of the entire suite use:
+
+.. code-block:: sh
+
+   python3 setup.py test  --addopts tests/cas/test_client
+
+pyest's `usage documentation section`_ details the different command line
+options that can be used when invoking the test runner.
+
+.. _usage documentation section: https://docs.pytest.org/en/latest/usage.html
+
+
+Test coverage
+~~~~~~~~~~~~~
+
+We are doing our best at keeping BuildGrid's test coverage score as high as
+possible. Doing so, we ask for any merge request to include necessary test
+additions and/or modifications in order to maintain that coverage level. A
+detailed `coverage report`_ is produced and publish for any change merged to the
+trunk.
+
+.. _coverage report: https://buildgrid.gitlab.io/buildgrid/coverage/
+
+
 .. _committer-access:
 
 Committer access
 ----------------
 
 We'll hand out commit access to anyone who has successfully landed a single
-patch to the code base. Please request this via irc or the mailing list.
+patch to the code base. Please request this via Slack or the mailing list.
 
 This of course relies on contributors being responsive and show willingness to
 address problems after landing branches there should not be any problems here.

docs/source/using.rst

@@ -9,5 +9,6 @@ This section covers how to run an use the BuildGrid build service.
 .. toctree::
    :maxdepth: 2
 
-   using_dummy_build.rst
-   using_simple_build.rst
+   using_internal.rst
+   using_bazel.rst
+   using_buildstream.rst

docs/source/using_bazel.rst

+
+.. _bazel-builds:
+
+Bazel builds
+============
+
+`Bazel`_ is a *“fast, scalable, multi-language and extensible build system”*
+that supports remote build execution using the remote execution API (REAPI) v2
+since its `0.17 release`_.
+
+.. _Bazel: https://bazel.build
+.. _0.17 release: https://blog.bazel.build/2018/09/14/bazel-0.17.html
+
+
+.. _bazel-configuration:
+
+Configuration
+-------------
+
+Bazel accepts many options that can either be specified as command line
+arguments when involking the ``bazel`` tool or stored in a `.bazelrc`_
+configuration file.
+
+In order to activate remote execution, Bazel's ``build`` subcommand needs to be
+given specific `build options`_. Most important ones include:
+
+- ``--remote_executor``: remote execution endpoint's location, ``{host}:{port}``.
+- ``--remote_instance_name``: remote execution instance's name.
+- ``--spawn_strategy``: action execution method.
+- ``--genrule_strategy``: `genrules`_ execution method.
+
+Spawn and genrule strategies need to be set to ``remote`` for remote execution.
+As an example, in order to activate remote execution on the ``main`` instance of
+the remote execution server available at ``controller.grid.build`` on port
+``50051`` you should amend your ``.bazelrc`` with:
+
+.. code-block:: sh
+
+   build --spawn_strategy=remote --genrule_strategy=remote --remote_executor=controller.grid.build:50051 --remote_instance_name=main
+
+.. _.bazelrc: https://docs.bazel.build/versions/master/user-manual.html#bazelrc
+.. _build options: https://docs.bazel.build/versions/master/command-line-reference.html#build-options
+.. _genrules: https://docs.bazel.build/versions/master/be/general.html#genrule
+
+
+.. _bazel-example:
+
+Example build
+-------------
+
+
+.. _bazel-build:
+
+Complete build
+--------------

docs/source/using_buildstream.rst

+
+.. _buildstream-builds:
+
+BuildStream builds
+==================
+

docs/source/using_dummy_build.rst

-.. _dummy-build:
-
-Dummy build
-===========
-
-In one terminal, start a server:
-
-.. code-block:: sh
-
-   bgd server start buildgrid/_app/settings/default.yml
-
-In another terminal, send a request for work:
-
-.. code-block:: sh
-
-   bgd execute request-dummy
-
-The stage should show as ``QUEUED`` as it awaits a bot to pick up the work:
-
-.. code-block:: sh
-
-   bgd execute list
-
-Create a bot session:
-
-.. code-block:: sh
-
-   bgd bot dummy
-
-Show the work as completed:
-
-.. code-block:: sh
-
-   bgd execute list

docs/source/using_simple_build.rst → docs/source/using_internal.rst

+
+.. _internal-builds:
+
+Internal builds
+===============
+
+
+.. _dummy-test:
+
+Dummy test
+----------
+
+In one terminal, start a server:
+
+.. code-block:: sh
+
+   bgd server start buildgrid/_app/settings/default.yml
+
+In another terminal, send a request for work:
+
+.. code-block:: sh
+
+   bgd execute request-dummy
+
+The stage should show as ``QUEUED`` as it awaits a bot to pick up the work:
+
+.. code-block:: sh
+
+   bgd execute list
+
+Create a bot session:
+
+.. code-block:: sh
+
+   bgd bot dummy
+
+Show the work as completed:
+
+.. code-block:: sh
+
+   bgd execute list
+
+
 .. _simple-build:
 
 Simple build
-============
+------------
 
 This example covers a simple build. The user will upload a directory containing
 a C file and a command to the CAS. The bot will then fetch the uploaded