Merge "[cfg01] Honor idf.net_config.mgmt.ip-range"

[fuel.git] / mcp / patches / README.rst

diff --git a/mcp/patches/README.rst b/mcp/patches/README.rst
index 735b703..28af0e8 100644 (file)
--- 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
 .. 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
 ==========================================
 
 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:
 
 
 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:
 
 
 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:
 ======================
 
 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
 ------------------------------------------------------
 
 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
 -------------------------
 
 
 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
 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:
 
 
 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
 -----------------------------------------
 
 
 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.