(buildstream) 02/02: doc: Document `disallow-subproject-uris`

[ju...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

juergbi pushed a commit to branch juerg/junction-aliases
in repository https://gitbox.apache.org/repos/asf/buildstream.git

commit 3d210e3c77f940210947bb1fd69d763bab72385b
Author: Jürg Billeter <j...@bitron.ch>
AuthorDate: Fri Apr 5 16:31:37 2024 +0200

    doc: Document `disallow-subproject-uris`
---
 doc/source/format_project.rst | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/doc/source/format_project.rst b/doc/source/format_project.rst
index 83eac5ea0..131b60cc7 100644
--- a/doc/source/format_project.rst
+++ b/doc/source/format_project.rst
@@ -204,6 +204,9 @@ URLs which are to be used in the individual ``.bst`` files.
      foo: git://git.foo.org/
      bar: http://bar.com/downloads/
 
+If you want this project's alias definitions to also be used for subprojects,
+see :ref:`Mapping source aliases of subprojects <project_junctions_source_aliases>`.
+
 
 Sandbox options
 ~~~~~~~~~~~~~~~
@@ -319,6 +322,9 @@ The mirrors can be overridden on a per project basis using
 be used first in the :ref:`user configuration <config_default_mirror>`, or using
 the  :ref:`--default-mirror <invoking_bst>` command-line argument.
 
+If you want this project's mirrors to also be used for subprojects,
+see :ref:`Mapping source aliases of subprojects <project_junctions_source_aliases>`.
+
 
 .. _project_plugins:
 
@@ -989,6 +995,31 @@ subproject.
    will not accrue runtime dependencies on elements in your *internal* subproject.
 
 
+.. _project_junctions_source_aliases:
+
+Mapping source aliases of subprojects
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+:mod:`junction <elements.junction>` elements allow source aliases of subprojects
+to be mapped to aliases of the parent project. This makes it possible to control
+the translation of aliases to URLs including mirror configuration across multiple
+project levels.
+
+To ensure that there are mappings for all aliases of all subprojects, you can set the
+``disallow-subproject-uris`` flag in the ``junctions`` group here in ``project.conf``.
+
+top-level
+
+.. code:: yaml
+
+   junctions:
+     disallow-subproject-uris: True
+
+This will raise an error if an alias without a mapping is encountered. This flag
+is applied recursively across all junctions. It also configures ``unaliased-url``
+as a fatal warning in all subprojects to ensure that the current project is in
+full control over all source URLs.
+
+
 .. _project_defaults:
 
 Element default configuration