[buildstream] 01/01: doc/source/format_project.rst: Clarifying behavior of project.refs regarding subprojects

[tv...@apache.org]

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

tvb pushed a commit to branch tristan/document-project-refs
in repository https://gitbox.apache.org/repos/asf/buildstream.git

commit 7bb5d713d4751b6282444d41850720e67dfa3aeb
Author: Tristan van Berkom <tr...@codethink.co.uk>
AuthorDate: Mon Jun 13 16:23:22 2022 +0900

    doc/source/format_project.rst: Clarifying behavior of project.refs regarding subprojects
---
 doc/source/format_project.rst | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/doc/source/format_project.rst b/doc/source/format_project.rst
index 6cb9f7893..435fdee41 100644
--- a/doc/source/format_project.rst
+++ b/doc/source/format_project.rst
@@ -140,6 +140,20 @@ following to your ``project.conf``:
 
   ref-storage: project.refs
 
+.. attention::
+
+   **Storing subproject source references in project.refs**
+
+   When using the ``project.refs`` file, it is possible to override the
+   references in subprojects by editing the ``project.refs`` file directly
+   or by using :ref:`bst source track --cross-junctions <invoking_source_track>`,
+   this can be practical to try out fresher versions of components which
+   are maintained in a subproject.
+
+   It should be noted however that overridden subproject source references listed
+   in your ``project.refs`` file will be ignored by projects which use your project
+   as a subproject.
+
 
 .. _configurable_warnings: