From 1cbc2e17f782d8765b33c092c42ebdd98510ae62 Mon Sep 17 00:00:00 2001
From: Jonathan Maw <jonathan.maw@codethink.co.uk>
Date: Wed, 27 Jun 2018 14:27:25 +0100
Subject: doc: Add documentation for source mirroring

---
 doc/source/format_project.rst | 37 +++++++++++++++++++++++++++++++++++++
 doc/source/using_config.rst   | 21 +++++++++++++++++++++
 2 files changed, 58 insertions(+)

(limited to 'doc')

diff --git a/doc/source/format_project.rst b/doc/source/format_project.rst
index 36de41a55..cf0970f77 100644
--- a/doc/source/format_project.rst
+++ b/doc/source/format_project.rst
@@ -198,6 +198,43 @@ You can also specify a list of caches here; earlier entries in the list
 will have higher priority than later ones.
 
 
+.. _project_essentials_mirrors:
+
+Mirrors
+~~~~~~~
+A list of mirrors can be defined that couple a location to a mapping of aliases to a
+list of URIs, e.g.
+
+.. code:: yaml
+
+  mirrors:
+  - name: middle-earth
+    aliases:
+      foo:
+      - http://www.middle-earth.com/foo/1
+      - http://www.middle-earth.com/foo/2
+      bar:
+      - http://www.middle-earth.com/bar/1
+      - http://www.middle-earth.com/bar/2
+  - name: oz
+    aliases:
+      foo:
+      - http://www.oz.com/foo
+      bar:
+      - http://www.oz.com/bar
+
+The order that the mirrors (and the URIs therein) are consulted is in the order
+they are defined when fetching, and in reverse-order when tracking.
+
+A default mirror to consult first can be defined via
+:ref:`user config <config_default_mirror>`, or the command-line argument
+:ref:`--default-mirror <invoking_bst>`.
+
+.. note::
+
+   The ``mirrors`` field is available since :ref:`format version 11 <project_format_version>`
+
+
 .. _project_plugins:
 
 External plugins
diff --git a/doc/source/using_config.rst b/doc/source/using_config.rst
index d02aaf3d4..c707cd04b 100644
--- a/doc/source/using_config.rst
+++ b/doc/source/using_config.rst
@@ -89,6 +89,27 @@ modifying some low level component.
    the ``--strict`` and ``--no-strict`` command line options.
 
 
+.. _config_default_mirror:
+
+Default Mirror
+~~~~~~~~~~~~~~
+When using :ref:`mirrors <project_essentials_mirrors>`, a default mirror can
+be defined to be fetched first.
+The default mirror is defined by its name, e.g.
+
+.. code:: yaml
+
+  projects:
+    project-name:
+      default-mirror: oz
+
+
+.. note::
+
+   It is possible to override this at invocation time using the
+   ``--default-mirror`` command-line option.
+
+
 Default configuration
 ---------------------
 The default BuildStream configuration is specified here for reference:
-- 
cgit v1.2.1