diff options
Diffstat (limited to 'mcp/patches/README.rst')
| -rw-r--r-- | mcp/patches/README.rst | 158 |
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. |