doc/source/format_project.rst: Clarifying behavior of project.refs regarding subprojects
diff --git a/doc/source/format_project.rst b/doc/source/format_project.rst
index 6cb9f78..435fdee 100644
--- a/doc/source/format_project.rst
+++ b/doc/source/format_project.rst
@@ -140,6 +140,20 @@
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:
