mcp/patches/README.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. SPDX-License-Identifier: CC-BY-4.0
   3 .. (c) 2018 Mirantis Inc., Enea AB and others.
   4
   5 ==========================================
   6 OPNFV Fuel Submodule Fetching and Patching
   7 ==========================================
   8
   9 This directory holds submodule fetching/patching scripts, intended for
  10 working with upstream Fuel/MCP components (e.g.: ``reclass-system-salt-model``)
  11 in developing/applying OPNFV patches (backports, custom fixes etc.).
  12
  13 The scripts should be friendly to the following 2 use-cases:
  14
  15 - development work: easily cloning, binding repos to specific commits,
  16   remote tracking, patch development etc.;
  17 - to provide parent build scripts an easy method of tracking upstream
  18   references and applying OPNFV patches on top;
  19
  20 Also, we need to support at least the following modes of operations:
  21
  22 - submodule bind - each submodule patches will be based on the commit ID
  23   saved in the ``.gitmodules`` config file;
  24 - remote tracking - each submodule will sync with the upstream remote
  25   and patches will be applied on top of ``<sub_remote>/<sub_branch>/HEAD``;
  26
  27 Workflow (Development)
  28 ======================
  29
  30 The standard development workflow should look as follows:
  31
  32 Decide whether remote tracking should be active or not
  33 ------------------------------------------------------
  34
  35 .. NOTE::
  36
  37     Setting the following var to any non-empty str enables remote track.
  38
  39 .. code-block:: console
  40
  41     developer@machine:~/fuel$ export FUEL_TRACK_REMOTES=""
  42
  43 Initialize git submodules
  44 -------------------------
  45
  46 All Fuel direct dependency projects are registered as submodules.
  47 If remote tracking is active, upstream remote is queried and latest remote
  48 branch ``HEAD`` is fetched. Otherwise, checkout commit IDs from ``.gitmodules``.
  49
  50 .. code-block:: console
  51
  52     developer@machine:~/fuel$ make -C mcp/patches sub
  53
  54 Apply patches from ``patches/<sub-project>/*`` to respective submodules
  55 -----------------------------------------------------------------------
  56
  57 This will result in creation of:
  58
  59 - a tag called ``${F_OPNFV_TAG}-root`` at the same commit as OPNFV Fuel
  60   upstream reference (bound to git submodule OR tracking remote ``HEAD``);
  61 - a new branch ``nightly`` which will hold all the OPNFV patches,
  62   each patch is applied on this new branch with ``git-am``;
  63 - a tag called ``${F_OPNFV_TAG}`` at ``nightly/HEAD``;
  64 - for each (sub)directory of ``patches/<sub-project>``, another pair of tags
  65   ``${F_OPNFV_TAG}-<sub-directory>-fuel/patch-root`` and
  66   ``${F_OPNFV_TAG}-<sub-directory>-fuel/patch`` are also created;
  67
  68 .. code-block:: console
  69
  70     developer@machine:~/fuel$ make -C mcp/patches patches-import
  71
  72 Modify sub-projects for whatever you need
  73 -----------------------------------------
  74
  75 To add/change OPNFV-specific patches for a sub-project:
  76
  77 - commit your changes inside the git submodule(s);
  78 - move the git tag to the new reference so ``make patches-export`` will
  79   pick up the new commit later;
  80
  81 .. code-block:: console
  82
  83     developer@machine:~/fuel$ cd ./path/to/submodule
  84     developer@machine:~/fuel/path/to/submodule$ # ...
  85     developer@machine:~/fuel/path/to/submodule$ git commit
  86     developer@machine:~/fuel/path/to/submodule$ git tag -f ${F_OPNFV_TAG}-fuel/patch
  87
  88 Re-create Patches
  89 -----------------
  90
  91 Each commit on ``nightly`` branch of each subproject will be
  92 exported to ``patches/subproject/`` via ``git format-patch``.
  93
  94 .. NOTE::
  95
  96     Only commit submodule file changes when you need to bump upstream refs.
  97
  98 .. WARNING::
  99
 100     DO NOT commit patched submodules!
 101
 102 .. code-block:: console
 103
 104     developer@machine:~/fuel$ make -C mcp/patches patches-export patches-copyright
 105
 106 Clean Workbench Branches and Tags
 107 ---------------------------------
 108
 109 .. code-block:: console
 110
 111     developer@machine:~/fuel$ make -C mcp/patches clean
 112
 113 De-initialize Submodules and Force a Clean Clone
 114 ------------------------------------------------
 115
 116 .. code-block:: console
 117
 118     developer@machine:~/fuel$ make -C mcp/patches deepclean
 119
 120 Sub-project Maintenance
 121 =======================
 122
 123 Adding a New Submodule
 124 ----------------------
 125
 126 If you need to add another subproject, you can do it with ``git submodule``.
 127 Make sure that you specify branch (with ``-b``), short name (with ``--name``):
 128
 129 .. code-block:: console
 130
 131     developer@machine:~/fuel$ git submodule -b master add --name reclass-system-salt-model \
 132                               https://github.com/Mirantis/reclass-system-salt-model \
 133                               mcp/reclass/classes/system
 134
 135 Working with Remote Tracking
 136 ----------------------------
 137
 138 Enable remote tracking as described above, which at ``make sub`` will update
 139 ALL submodules (e.g. ``reclass-system-salt-model``) to remote branch (set in
 140 ``.gitmodules``) ``HEAD``.
 141
 142 .. WARNING::
 143
 144     Enforce ``FUEL_TRACK_REMOTES`` to ``yes`` only if you want to constatly
 145     use the latest remote branch ``HEAD`` (as soon as upstream pushes a change
 146     on that branch, our next build will automatically include it - risk of our
 147     patches colliding with new upstream changes) - for **ALL** submodules.