From 6bf78c0734f0ff22fe0eef090b794f0a1b1a3fb8 Mon Sep 17 00:00:00 2001
From: Tristan van Berkom <tristan@codethink.co.uk>
Date: Sat, 31 Oct 2020 22:15:08 +0900
Subject: plugins/elements/junction.py: Documenting element overrides.

---
 src/buildstream/plugins/elements/junction.py | 78 +++++++++++++++++++++++++++-
 1 file changed, 76 insertions(+), 2 deletions(-)

diff --git a/src/buildstream/plugins/elements/junction.py b/src/buildstream/plugins/elements/junction.py
index 8693313af..cc980bec3 100644
--- a/src/buildstream/plugins/elements/junction.py
+++ b/src/buildstream/plugins/elements/junction.py
@@ -48,8 +48,7 @@ Overview
      # Optionally look in a subpath of the source repository for the project
      path: projects/hello
 
-     # Optionally override junction configurations in the subproject
-     # with a junction declaration in this project.
+     # Optionally override elements in subprojects, including junctions.
      #
      overrides:
        subproject-junction.bst: local-junction.bst
@@ -138,6 +137,79 @@ configuration in a subproject which matches the toplevel project's
 configuration.
 
 
+Overriding elements
+-------------------
+It is possible to override elements in subprojects. This can be useful if for
+example, you need to work with a custom variant or fork of some software in the
+subproject. This is a better strategy than overlapping and overwriting shared
+libraries built by the subproject later on, as we can ensure that reverse dependencies
+in the subproject are built against the overridden element.
+
+Overridding elements allows you to build on top of an existing project
+and benefit from updates and releases for the vast majority of the upstream project,
+even when there are some parts of the upstream project which need to be customized
+for your own applications.
+
+Even junction elements in subprojects can be overridden, this is sometimes important
+in order to reconcile conflicts when multiple projects depend on the same subproject,
+as :ref:`discussed below <core_junction_nested_overrides>`.
+
+.. code:: yaml
+
+   kind: junction
+
+   ...
+
+   config:
+
+     # Override elements in a junctioned project
+     #
+     overrides:
+       subproject-element.bst: local-element.bst
+
+It is also possible to override elements in deeply nested subprojects, using
+project relative :ref:`junction paths <format_element_names>`:
+
+.. code:: yaml
+
+   kind: junction
+
+   ...
+
+   config:
+
+     # Override deeply nested elements
+     #
+     overrides:
+       subproject.bst:subsubproject-element.bst: local-element.bst
+
+.. attention::
+
+   Overriding an element causes your project to completely define the
+   element being overridden, which means you will no longer receive updates
+   or security patches to the element in question when updating to newer
+   versions and releases of the upstream project.
+
+   As such, overriding elements is only recommended in cases where the
+   element is very significantly redefined.
+
+   Such cases include cases when you need a newer version of the element than
+   the one maintained by the upstream project you are using as a subproject,
+   or when you have significanly modified the code in your own custom ways.
+
+   If you only need to introduce a security patch, then it is recommended that
+   you create your own downstream branch of the upstream project, not only will
+   this allow you to more easily consume updates with VCS tools like ``git rebase``,
+   but it will also be more convenient for submitting your security patches
+   to the upstream project so that you can drop them in a future update.
+
+   Similarly, if you only need to enable/disable a specific feature of a module,
+   it is also preferrable to use a downstream branch of the upstream project.
+   In such a case, it is also worth trying to convince the upstream project to
+   support a :ref:`project option <project_options>` for your specific element
+   configuration, if it would be of use to other users too.
+
+
 .. _core_junction_nested:
 
 Nested Junctions
@@ -152,6 +224,8 @@ the user to resolve conflicting nested junctions, and will provide an error
 message whenever a conflict is detected.
 
 
+.. _core_junction_nested_overrides:
+
 Overriding subproject junctions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 If your project and a subproject share a subproject in common, then one way
-- 
cgit v1.2.1