docs: Add documentation for Configurable Warnings

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

This also adds a deprecation notice to the fail on overlaps section.

buildstream/plugin.py

@@ -47,6 +47,24 @@ 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
+---------------------
+For plugins which wish to provide configurable warnings, it is necessary to override
+:func:`Plugin.get_warnings() <buildstream.plugin.Plugin.get_warnings>` to get them registered
+with buildstream.
+
+These warnings are used when calling :func:`Plugin.warn() <buildstream.plugin.Plugin.warn>` as an optional
+parameter ``warning_token``, this will raise a :class:`PluginError` if the warning is configured as fatal.
+
+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>`.
+
+Example
+~~~~~~~
+If the ``git.py`` plugin made the warning ``"inconsistent-submodule"`` available through
+:func:`Plugin.get_warnings() <buildstream.plugin.Plugin.get_warnings>` then it could be referenced in project
+configuration as ``"git:inconsistent-submodule"``
 
 Plugin Structure
 ----------------

doc/source/format_project.rst

@@ -126,23 +126,72 @@ following to your ``project.conf``:
    The ``ref-storage`` configuration is available since :ref:`format version 8 <project_format_version>`
 
 
+.. _configurable_warnings:
+
+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.
+
+When ``fatal-warnings`` is True, all configurable fatal warnings will be set as fatal. Individual warnings
+can also be set by setting ``fatal-warnings`` to a list of warnings.
+
+.. code::
+
+  fatal-warnings:
+  - core:overlaps
+  - core:ref-not-in-track
+  - <plugin>:<warning>
+
+Core Configurable warnings include:
+
+- :ref:`core:overlaps <fail_on_overlaps>`
+- :ref:`core:ref-not-in-track <ref_not_in_track>`
+
+.. note::
+
+  The ``ref-storage`` configuration is available since :ref:`format version 12 <project_format_version>`
+
+.. note::
+
+  Other configurable warnings are plugin specific and should be noted within their individual documentation.
+
+.. _fail_on_overlaps:
+
 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.
 
-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.
+.. deprecated:: 1.4
+
 
-otherwise, a warning will be raised indicating which files had overlaps,
-and the order that the elements were overlapped.
+  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.
+
+  Otherwise, a warning will be raised indicating which files had overlaps,
+  and the order that the elements were overlapped.
 
 .. code:: yaml
 
+  # Deprecated
   fail-on-overlap: true
 
+.. note::
+
+  Since deprecation in :ref:`format version 12 <project_format_version>` the recommended
+  solution to this is :ref:`Configurable Warnings <configurable_warnings>`
+
+
+.. _ref_not_in_track:
+
+Ref not in track
+~~~~~~~~~~~~~~~~
+The configured ref is not valid for the configured track.
+
 
 .. _project_source_aliases: