Merge "[docs] Refresh for Gambia release" into stable/gambia

1 files changed, 80 insertions, 78 deletions

diff --git a/mcp/patches/README.rst b/mcp/patches/README.rst
index 735b70341..28af0e8f7 100644
--- a/mcp/patches/README.rst
+++ b/mcp/patches/README.rst
@@ -1,30 +1,30 @@
 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
 .. SPDX-License-Identifier: CC-BY-4.0
-.. (c) 2017 Mirantis Inc., Enea AB and others.
+.. (c) 2018 Mirantis Inc., Enea AB and others.
 
 ==========================================
-Fuel@OPNFV submodule fetching and patching
+OPNFV Fuel Submodule Fetching and Patching
 ==========================================
 
 This directory holds submodule fetching/patching scripts, intended for
-working with upstream Fuel/MCP components (e.g.: reclass-system-salt-model) in
-developing/applying OPNFV patches (backports, custom fixes etc.).
+working with upstream Fuel/MCP components (e.g.: ``reclass-system-salt-model``)
+in developing/applying OPNFV patches (backports, custom fixes etc.).
 
 The scripts should be friendly to the following 2 use-cases:
 
-  - development work: easily cloning, binding repos to specific commits,
-    remote tracking, patch development etc.;
-  - to provide parent build scripts an easy method of tracking upstream
-    references and applying OPNFV patches on top;
+- development work: easily cloning, binding repos to specific commits,
+  remote tracking, patch development etc.;
+- to provide parent build scripts an easy method of tracking upstream
+  references and applying OPNFV patches on top;
 
 Also, we need to support at least the following modes of operations:
 
-  - submodule bind - each submodule patches will be based on the commit ID
-    saved in the .gitmodules config file;
-  - remote tracking - each submodule will sync with the upstream remote
-    and patches will be applied on top of <sub_remote>/<sub_branch>/HEAD;
+- submodule bind - each submodule patches will be based on the commit ID
+  saved in the ``.gitmodules`` config file;
+- remote tracking - each submodule will sync with the upstream remote
+  and patches will be applied on top of ``<sub_remote>/<sub_branch>/HEAD``;
 
-Workflow (development)
+Workflow (Development)
 ======================
 
 The standard development workflow should look as follows:
@@ -32,114 +32,116 @@ The standard development workflow should look as follows:
 Decide whether remote tracking should be active or not
 ------------------------------------------------------
 
-NOTE: Setting the following var to any non-empty str enables remote track.
+.. NOTE::
 
-NOTE: Leaving unset will enable remote track for anything but stable branch.
+    Setting the following var to any non-empty str enables remote track.
 
-    .. code-block:: bash
+.. code-block:: console
 
-        $ export FUEL_TRACK_REMOTES=""
+    developer@machine:~/fuel$ export FUEL_TRACK_REMOTES=""
 
 Initialize git submodules
 -------------------------
 
-All Fuel sub-projects are registered as submodules.
+All Fuel direct dependency projects are registered as submodules.
 If remote tracking is active, upstream remote is queried and latest remote
-branch HEAD is fetched. Otherwise, checkout commit IDs from .gitmodules.
+branch ``HEAD`` is fetched. Otherwise, checkout commit IDs from ``.gitmodules``.
 
-    .. code-block:: bash
+.. code-block:: console
 
-        $ make sub
+    developer@machine:~/fuel$ make -C mcp/patches sub
 
-Apply patches from `patches/<sub-project>/*` to respective submodules
----------------------------------------------------------------------
+Apply patches from ``patches/<sub-project>/*`` to respective submodules
+-----------------------------------------------------------------------
 
 This will result in creation of:
 
-- a tag called `${FUEL_MAIN_TAG}-opnfv-root` at the same commit as Fuel@OPNFV
-  upstream reference (bound to git submodule OR tracking remote HEAD);
-- a new branch `opnfv-fuel` which will hold all the OPNFV patches,
-  each patch is applied on this new branch with `git-am`;
-- a tag called `${FUEL_MAIN_TAG}-opnfv` at `opnfv-fuel/HEAD`;
+- a tag called ``${F_OPNFV_TAG}-root`` at the same commit as OPNFV Fuel
+  upstream reference (bound to git submodule OR tracking remote ``HEAD``);
+- a new branch ``nightly`` which will hold all the OPNFV patches,
+  each patch is applied on this new branch with ``git-am``;
+- a tag called ``${F_OPNFV_TAG}`` at ``nightly/HEAD``;
+- for each (sub)directory of ``patches/<sub-project>``, another pair of tags
+  ``${F_OPNFV_TAG}-<sub-directory>-fuel/patch-root`` and
+  ``${F_OPNFV_TAG}-<sub-directory>-fuel/patch`` are also created;
 
-    .. code-block:: bash
+.. code-block:: console
 
-        $ make patches-import
+    developer@machine:~/fuel$ make -C mcp/patches patches-import
 
 Modify sub-projects for whatever you need
 -----------------------------------------
 
-Commit your changes when you want them taken into account in the build.
+To add/change OPNFV-specific patches for a sub-project:
 
-Re-create patches
+- commit your changes inside the git submodule(s);
+- move the git tag to the new reference so ``make patches-export`` will
+  pick up the new commit later;
+
+.. code-block:: console
+
+    developer@machine:~/fuel$ cd ./path/to/submodule
+    developer@machine:~/fuel/path/to/submodule$ # ...
+    developer@machine:~/fuel/path/to/submodule$ git commit
+    developer@machine:~/fuel/path/to/submodule$ git tag -f ${F_OPNFV_TAG}-fuel/patch
+
+Re-create Patches
 -----------------
 
-Each commit on `opnfv-fuel` branch of each subproject will be
-exported to `patches/subproject/` via `git format-patch`.
+Each commit on ``nightly`` branch of each subproject will be
+exported to ``patches/subproject/`` via ``git format-patch``.
+
+.. NOTE::
+
+    Only commit submodule file changes when you need to bump upstream refs.
 
-NOTE: Only commit (-f) submodules when you need to bump upstream ref.
+.. WARNING::
 
-NOTE: DO NOT commit patched submodules!
+    DO NOT commit patched submodules!
 
-    .. code-block:: bash
+.. code-block:: console
 
-        $ make patches-export
+    developer@machine:~/fuel$ make -C mcp/patches patches-export patches-copyright
 
-Clean workbench branches and tags
+Clean Workbench Branches and Tags
 ---------------------------------
 
-    .. code-block:: bash
+.. code-block:: console
 
-        $ make clean
+    developer@machine:~/fuel$ make -C mcp/patches clean
 
-De-initialize submodules and force a clean clone
+De-initialize Submodules and Force a Clean Clone
 ------------------------------------------------
 
-    .. code-block:: bash
+.. code-block:: console
 
-        $ make deepclean
+    developer@machine:~/fuel$ make -C mcp/patches deepclean
 
-Sub-project maintenance
+Sub-project Maintenance
 =======================
 
-Adding a new submodule
+Adding a New Submodule
 ----------------------
 
-If you need to add another subproject, you can do it with `git submodule`.
-Make sure that you specify branch (with `-b`), short name (with `--name`):
-
-    .. code-block:: bash
-
-        $ git submodule -b master add --name reclass-system-salt-model
-          https://github.com/Mirantis/reclass-system-salt-model
-          relative/path/to/submodule
-
-Working with remote tracking for upgrading Fuel components
-----------------------------------------------------------
-
-Enable remote tracking as described above, which at `make sub` will update
-ALL submodules (e.g. reclass-system-salt-model) to remote branch (set in
-.gitmodules) HEAD.
+If you need to add another subproject, you can do it with ``git submodule``.
+Make sure that you specify branch (with ``-b``), short name (with ``--name``):
 
-* If upstream has NOT already tagged a new version, we can still work on
-  our patches, make sure they apply etc., then check for new upstream
-  changes (and that our patches still apply on top of them) by:
+.. code-block:: console
 
-* If upstream has already tagged a new version we want to pick up, checkout
-  the new tag in each submodule:
+    developer@machine:~/fuel$ git submodule -b master add --name reclass-system-salt-model \
+                              https://github.com/Mirantis/reclass-system-salt-model \
+                              mcp/reclass/classes/system
 
-* Once satisfied with the patch and submodule changes, commit them:
+Working with Remote Tracking
+----------------------------
 
-  - enforce FUEL_TRACK_REMOTES to "yes" if you want to constatly use the
-    latest remote branch HEAD (as soon as upstream pushes a change on that
-    branch, our next build will automatically include it - risk of our
-    patches colliding with new upstream changes);
-  - stage patch changes if any;
-  - if submodule tags have been updated (relevant when remote tracking is
-    disabled, i.e. we have a stable upstream baseline), add submodules;
+Enable remote tracking as described above, which at ``make sub`` will update
+ALL submodules (e.g. ``reclass-system-salt-model``) to remote branch (set in
+``.gitmodules``) ``HEAD``.
 
-        .. code-block:: bash
+.. WARNING::
 
-            $ make deepclean patches-import
-            $ git submodule foreach 'git checkout <newtag>'
-            $ make deepclean sub && git add -f relative/path/to/submodule
+    Enforce ``FUEL_TRACK_REMOTES`` to ``yes`` only if you want to constatly
+    use the latest remote branch ``HEAD`` (as soon as upstream pushes a change
+    on that branch, our next build will automatically include it - risk of our
+    patches colliding with new upstream changes) - for **ALL** submodules.