docs: Add documentation for Configurable Warnings

This includes detailing the use of `fatal-warnings` within project.conf

2 files changed, 36 insertions, 12 deletions

diff --git a/buildstream/plugin.py b/buildstream/plugin.py
index a60b501eb..8dbd89cc1 100644
--- a/buildstream/plugin.py
+++ b/buildstream/plugin.py
@@ -47,6 +47,23 @@ it is mandatory to implement the following abstract methods:
   Once all configuration has been loaded and preflight checks have passed,
   this method is used to inform the core of a plugin's unique configuration.
 
+Configurable Warnings
+---------------------
+Warnings raised through calling :func:`Plugin.warn() <buildstream.plugin.Plugin.warn>` can provide an optional
+parameter ``warning_token``, this will raise a :class:`PluginError` if the warning is configured as fatal within
+the project configuration.
+
+Configurable warnings will be prefixed with :func:`Plugin.get_kind() <buildstream.plugin.Plugin.get_kind>`
+within buildstream and must be prefixed as such in project configurations. For more detail on project configuration
+see :ref:`Configurable Warnings <configurable_warnings>`.
+
+It is important to document these warnings in your plugin documentation to allow users to make full use of them
+while configuring their projects.
+
+Example
+~~~~~~~
+If the :class:`git <buildstream.plugins.sources.git.GitSource>` plugin uses the warning ``"inconsistent-submodule"``
+then it could be referenced in project configuration as ``"git:inconsistent-submodule"``.
 
 Plugin Structure
 ----------------
@@ -808,7 +825,7 @@ class CoreWarnings():
     OVERLAPS = "overlaps"
     """
     This warning will be produced when buildstream detects an overlap on an element
-        which is not whitelisted.
+        which is not whitelisted. See :ref:`Overlap Whitelist <public_overlap_whitelist>`
     """
 
     REF_NOT_IN_TRACK = "ref-not-in-track"
diff --git a/doc/source/format_project.rst b/doc/source/format_project.rst
index cf4425a0f..1d55bd7e9 100644
--- a/doc/source/format_project.rst
+++ b/doc/source/format_project.rst
@@ -126,22 +126,29 @@ following to your ``project.conf``:
    The ``ref-storage`` configuration is available since :ref:`format version 8 <project_format_version>`
 
 
-Fail on overlaps
-~~~~~~~~~~~~~~~~
-When multiple elements are staged, there's a possibility that different
-elements will try and stage different versions of the same file.
+.. _configurable_warnings:
 
-When ``fail-on-overlap`` is true, if an overlap is detected
-that hasn't been allowed by the element's
-:ref:`overlap whitelist<public_overlap_whitelist>`,
-then an error will be raised and the build will fail.
+Configurable Warnings
+~~~~~~~~~~~~~~~~~~~~~
+Warnings can be configured as fatal using the ``fatal-warnings`` configuration item.
+When a warning is configured as fatal, where a warning would usually be thrown instead an error will be thrown
+causing the build to fail.
 
-otherwise, a warning will be raised indicating which files had overlaps,
-and the order that the elements were overlapped.
+Individual warnings can be configured as fatal by setting ``fatal-warnings`` to a list of warnings.
 
 .. code:: yaml
 
-  fail-on-overlap: true
+  fatal-warnings:
+  - overlaps
+  - ref-not-in-track
+  - <plugin>:<warning>
+
+BuildStream provides a collection of :class:`Core Warnings <buildstream.plugin.CoreWarnings>` which may be raised
+by a variety of plugins. Other configurable warnings are plugin specific and should be noted within their individual documentation.
+
+.. note::
+
+  The ``fatal-warnings`` configuration is available since :ref:`format version 16 <project_format_version>`
 
 
 .. _project_source_aliases: