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) 2017 Mirantis Inc., Enea AB and others.
   4
   5 ==========================================
   6 Fuel@OPNFV 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) in
  11 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: Setting the following var to any non-empty str enables remote track.
  36
  37 NOTE: Leaving unset will enable remote track for anything but stable branch.
  38
  39     .. code-block:: bash
  40
  41         $ export FUEL_TRACK_REMOTES=""
  42
  43 Initialize git submodules
  44 -------------------------
  45
  46 All Fuel sub-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:: bash
  51
  52         $ make 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 `${FUEL_MAIN_TAG}-opnfv-root` at the same commit as Fuel@OPNFV
  60   upstream reference (bound to git submodule OR tracking remote HEAD);
  61 - a new branch `opnfv-fuel` which will hold all the OPNFV patches,
  62   each patch is applied on this new branch with `git-am`;
  63 - a tag called `${FUEL_MAIN_TAG}-opnfv` at `opnfv-fuel/HEAD`;
  64
  65     .. code-block:: bash
  66
  67         $ make patches-import
  68
  69 Modify sub-projects for whatever you need
  70 -----------------------------------------
  71
  72 Commit your changes when you want them taken into account in the build.
  73
  74 Re-create patches
  75 -----------------
  76
  77 Each commit on `opnfv-fuel` branch of each subproject will be
  78 exported to `patches/subproject/` via `git format-patch`.
  79
  80 NOTE: Only commit (-f) submodules when you need to bump upstream ref.
  81
  82 NOTE: DO NOT commit patched submodules!
  83
  84     .. code-block:: bash
  85
  86         $ make patches-export
  87
  88 Clean workbench branches and tags
  89 ---------------------------------
  90
  91     .. code-block:: bash
  92
  93         $ make clean
  94
  95 De-initialize submodules and force a clean clone
  96 ------------------------------------------------
  97
  98     .. code-block:: bash
  99
 100         $ make deepclean
 101
 102 Sub-project maintenance
 103 =======================
 104
 105 Adding a new submodule
 106 ----------------------
 107
 108 If you need to add another subproject, you can do it with `git submodule`.
 109 Make sure that you specify branch (with `-b`), short name (with `--name`):
 110
 111     .. code-block:: bash
 112
 113         $ git submodule -b master add --name reclass-system-salt-model
 114           https://github.com/Mirantis/reclass-system-salt-model
 115           relative/path/to/submodule
 116
 117 Working with remote tracking for upgrading Fuel components
 118 ----------------------------------------------------------
 119
 120 Enable remote tracking as described above, which at `make sub` will update
 121 ALL submodules (e.g. reclass-system-salt-model) to remote branch (set in
 122 .gitmodules) HEAD.
 123
 124 * If upstream has NOT already tagged a new version, we can still work on
 125   our patches, make sure they apply etc., then check for new upstream
 126   changes (and that our patches still apply on top of them) by:
 127
 128 * If upstream has already tagged a new version we want to pick up, checkout
 129   the new tag in each submodule:
 130
 131 * Once satisfied with the patch and submodule changes, commit them:
 132
 133   - enforce FUEL_TRACK_REMOTES to "yes" if you want to constatly use the
 134     latest remote branch HEAD (as soon as upstream pushes a change on that
 135     branch, our next build will automatically include it - risk of our
 136     patches colliding with new upstream changes);
 137   - stage patch changes if any;
 138   - if submodule tags have been updated (relevant when remote tracking is
 139     disabled, i.e. we have a stable upstream baseline), add submodules;
 140
 141         .. code-block:: bash
 142
 143             $ make deepclean patches-import
 144             $ git submodule foreach 'git checkout <newtag>'
 145             $ make deepclean sub && git add -f relative/path/to/submodule