From efb4a4f6376600664220af2c90aaa8981e0258ec Mon Sep 17 00:00:00 2001
From: Matthias Schiffer <mschiffer@universe-factory.net>
Date: Fri, 31 Dec 2021 02:48:20 +0100
Subject: [PATCH] docs: user/getting_started: add a footnote regarding `make
 update`

Add some explanation when `make update` needs to be run again.
---
 docs/dev/basics.rst           |  1 +
 docs/user/getting_started.rst | 14 ++++++++++++--
 2 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/docs/dev/basics.rst b/docs/dev/basics.rst
index 8608567e..27ba23d3 100644
--- a/docs/dev/basics.rst
+++ b/docs/dev/basics.rst
@@ -23,6 +23,7 @@ webbrowser. You're welcome to join us!
 .. _hackint: https://hackint.org/
 .. _webchat: https://webirc.hackint.org/#irc://irc.hackint.org/#gluon
 
+.. _working-with-repositories:
 
 Working with repositories
 -------------------------
diff --git a/docs/user/getting_started.rst b/docs/user/getting_started.rst
index a7b9d0cb..01e01b54 100644
--- a/docs/user/getting_started.rst
+++ b/docs/user/getting_started.rst
@@ -86,10 +86,10 @@ Extensive documentation about the site configuration can be found at:
 site directory should always be a git repository by itself; committing site-specific files
 to the Gluon main repository should be avoided, as it will make updates more complicated.
 
-Next go back to the top-level Gluon directory and build Gluon::
+Next go back to the top-level Gluon directory and build Gluon\ [#make_update]_::
 
   cd ..
-  make update                        # Get other repositories used by Gluon
+  make update                       # Get other repositories used by Gluon
   make GLUON_TARGET=ath79-generic   # Build Gluon
 
 In case of errors read the messages carefully and try to fix the stated issues
@@ -125,6 +125,16 @@ These can be used for debugging and should be stored along with the images to
 allow debugging of kernel problems on devices in the field.
 See :ref:`Debugging <dev-debugging-kernel-oops>` for more information.
 
+.. rubric:: Footnotes
+
+.. [#make_update] ``make update`` only needs to be called again after updating the
+  Gluon repository (using ``git pull`` or similar) or after changing branches,
+  not for each build. Running it more often than necessary is undesirable, as
+  the update will take some time, and may undo manual modifications of the
+  external repositories while developing on Gluon.
+
+  See :ref:`working-with-repositories` for more information.
+
 Cleaning the build tree
 .......................