From f53f240b49e0c331a02ba297619772f5e0dc5449 Mon Sep 17 00:00:00 2001
From: Martin Curlej <mcurlej@redhat.com>
Date: Oct 14 2020 07:17:06 +0000
Subject: Added documentation for static contexts


Signed-off-by: Martin Curlej <mcurlej@redhat.com>

---

diff --git a/docs/HOW_MBS_BUILDS_MODULES.rst b/docs/HOW_MBS_BUILDS_MODULES.rst
index 7a845cf..89c2138 100644
--- a/docs/HOW_MBS_BUILDS_MODULES.rst
+++ b/docs/HOW_MBS_BUILDS_MODULES.rst
@@ -79,6 +79,11 @@ Such expanded modulemd files are then added to database as the next step in
 The ``submit_module_build(...)`` then moves the module builds to "init" state and sends a message on
 the configured message bus.
 
+There is a build option for MBS which enables us to override stream expansion and define contexts
+directly. For more information see |docs/STATIC_CONTEXTS.rst|_.
+
+.. |docs/STATIC_CONTEXTS.rst| replace:: ``docs/STATIC_CONTEXTS.rst``
+.. _docs/STATIC_CONTEXTS.rst: STATIC_CONTEXTS.rst
 
 Backend handles module moved to the "init" state
 ------------------------------------------------
diff --git a/docs/STATIC_CONTEXTS.rst b/docs/STATIC_CONTEXTS.rst
new file mode 100644
index 0000000..8f96d6c
--- /dev/null
+++ b/docs/STATIC_CONTEXTS.rst
@@ -0,0 +1,52 @@
+Static contexts
+===============
+
+- the user can specifically set their own context and dependencies when required through
+  ``mbs_options``. ``mbs_options`` is a dict which is part of the ``xmd`` property and
+  is used to configure additional build options for MBS. To make static contexts work,
+  you need to define ``contexts`` dict inside ``mbs_options`` property.
+- The context definition needs to be defined in the initial modulemd yaml file. ``contexts``
+  build property overrides any dependencies set through the ``dependencies`` property.
+- `static contexts` and `stream expansion` are mutually exclusive i. e. the streams defined in
+  ``buildrequires`` and ``requires`` of `static context` will not be expanded and need
+  to be precisely defined by the user. (You can not use `stream expansion` notation as ``[]``
+  or ``-f28`` as this will result in an error)
+- `static contexts` only override ``context`` of a module stream i. e. the one which
+  is the part of the module streams NSVC. ``build context`` is still calculated and preserved
+  in the resulting build in ``mbs`` property in ``xmd`` so the reuse of builds with the
+  same ``build contexts`` takes place.
+- as per design of the modulemdlib the only types which can be put inside of the ``xmd``
+  property are ``dict`` and ``string``.
+
+
+**Example**:
+
+::
+
+    .
+    .
+    .
+    xmd:
+        mbs_options:
+            contexts:
+                context1:
+                    buildrequires:
+                        module1: stream1
+                        .
+                        .
+                        .
+                        moduleN: streamN
+                    requires:
+                        moduleN: stream1
+                        .
+                        .
+                        .
+                        moduleN: streamN
+                .
+                .
+                .
+                contextN:
+                    .
+                    .
+                    .
+