doc: Explain overlap-whitelist and fail-on-overlap164-minimise-overlaps-by-having-overlaps-raise-exceptions-unless-configured-not-to

2 files changed, 40 insertions, 0 deletions

diff --git a/doc/source/projectconf.rst b/doc/source/projectconf.rst
index d7f609b39..9af52d65a 100644
--- a/doc/source/projectconf.rst
+++ b/doc/source/projectconf.rst
@@ -190,6 +190,23 @@ system.
      elements:
        potato: 0
 
+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.
+
+otherwise, a warning will be raised indicating which files had overlaps,
+and the order that the elements were overlapped.
+
+.. code:: yaml
+
+  fail-on-overlap: true
+
 
 .. _project_options:
 
diff --git a/doc/source/public.rst b/doc/source/public.rst
index 7a0da8e63..b9468cb00 100644
--- a/doc/source/public.rst
+++ b/doc/source/public.rst
@@ -82,3 +82,26 @@ then applied as a glob style match, as understood by
 This is used for creating compositions with the :mod:`compose <elements.compose>`
 element and can be used by other deployment related elements for the purpose of
 splitting element artifacts into separate packages.
+
+
+.. _public_overlap_whitelist:
+
+Overlap whitelist
+-----------------
+
+The overlap whitelist indicates which files this element is allowed to overlap
+over other elements when staged together with other elements.
+
+Each item in the overlap whitelist has substitutions applied from
+:ref:`variables <format_variables>`, and is then applied as a glob-style match
+(i.e. :func:`utils.glob() <buildstream.utils.glob>`).
+
+.. code:: yaml
+
+  public:
+    bst:
+      overlap-whitelist:
+      - |
+        %{sysconfdir}/*
+      - |
+        /etc/fontcache