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.
5 ==========================================
6 OPNFV Fuel Submodule Fetching and Patching
7 ==========================================
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.).
13 The scripts should be friendly to the following 2 use-cases:
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;
20 Also, we need to support at least the following modes of operations:
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``;
27 Workflow (Development)
28 ======================
30 The standard development workflow should look as follows:
32 Decide whether remote tracking should be active or not
33 ------------------------------------------------------
37 Setting the following var to any non-empty str enables remote track.
39 .. code-block:: console
41 developer@machine:~/fuel$ export FUEL_TRACK_REMOTES=""
43 Initialize git submodules
44 -------------------------
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``.
50 .. code-block:: console
52 developer@machine:~/fuel$ make -C mcp/patches sub
54 Apply patches from ``patches/<sub-project>/*`` to respective submodules
55 -----------------------------------------------------------------------
57 This will result in creation of:
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;
68 .. code-block:: console
70 developer@machine:~/fuel$ make -C mcp/patches patches-import
72 Modify sub-projects for whatever you need
73 -----------------------------------------
75 To add/change OPNFV-specific patches for a sub-project:
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;
81 .. code-block:: console
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
91 Each commit on ``nightly`` branch of each subproject will be
92 exported to ``patches/subproject/`` via ``git format-patch``.
96 Only commit submodule file changes when you need to bump upstream refs.
100 DO NOT commit patched submodules!
102 .. code-block:: console
104 developer@machine:~/fuel$ make -C mcp/patches patches-export patches-copyright
106 Clean Workbench Branches and Tags
107 ---------------------------------
109 .. code-block:: console
111 developer@machine:~/fuel$ make -C mcp/patches clean
113 De-initialize Submodules and Force a Clean Clone
114 ------------------------------------------------
116 .. code-block:: console
118 developer@machine:~/fuel$ make -C mcp/patches deepclean
120 Sub-project Maintenance
121 =======================
123 Adding a New Submodule
124 ----------------------
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``):
129 .. code-block:: console
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
135 Working with Remote Tracking
136 ----------------------------
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``.
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.