build/f_repos/README.md

   1 Fuel@OPNFV submodule fetching and patching
   2 ==========================================
   3
   4 This directory holds submodule fetching/patching scripts, intended for
   5 working with upstream Fuel components (fuel-library, ... , fuel-ui) in
   6 developing/applying OPNFV patches (backports, custom fixes etc.).
   7
   8 The scripts should be friendly to the following 2 use-cases:
   9   - development work: easily cloning, binding repos to specific commits,
  10     remote tracking, patch development etc.;
  11   - to provide parent build scripts an easy method of tracking upstream
  12     references and applying OPNFV patches on top;
  13
  14 Also, we need to support at least the following modes of operations:
  15   - submodule bind - each submodule patches will be based on the commit ID
  16     saved in the .gitmodules config file;
  17   - remote tracking - each submodule will sync with the upstream remote
  18     and patches will be applied on top of <sub_remote>/<sub_branch>/HEAD;
  19
  20 Workflow (development)
  21 ----------------------
  22 The standard development workflow should look as follows:
  23
  24 1. Decide whether remote tracking should be active or not:
  25    NOTE: Setting the following var to any non-empty str enables remote track.
  26    NOTE: Leaving unset will enable remote track for anything but stable branch.
  27
  28    $ export FUEL_TRACK_REMOTES=""
  29
  30 2. All Fuel sub-projects are registered as submodules. To initialize them, call:
  31    If remote tracking is active, upstream remote is queried and latest remote
  32    branch HEAD is fetched. Otherwise, checkout commit IDs from .gitmodules.
  33
  34    $ make sub
  35
  36 3. Apply patches from `patches/<sub-project>/*` to respective submodules via:
  37
  38    $ make patches-import
  39
  40    This will result in creation of:
  41    - a tag called `${FUEL_MAIN_TAG}-opnfv-root` at the same commit as Fuel@OPNFV
  42      upstream reference (bound to git submodule OR tracking remote HEAD);
  43    - a new branch `opnfv-fuel` which will hold all the OPNFV patches,
  44      each patch is applied on this new branch with `git-am`;
  45    - a tag called `${FUEL_MAIN_TAG}-opnfv` at `opnfv-fuel/HEAD`;
  46
  47 4. Modify sub-projects for whatever you need.
  48    Commit your changes when you want them taken into account in the build.
  49
  50 5. Re-create patches via:
  51
  52    $ make patches-export
  53
  54    Each commit on `opnfv-fuel` branch of each subproject will be
  55    exported to `patches/subproject/` via `git format-patch`.
  56
  57    NOTE: Only commit (-f) submodules when you need to bump upstream ref.
  58    NOTE: DO NOT commit patched submodules!
  59
  60 6. Clean workbench branches and tags with:
  61
  62    $ make clean
  63
  64 7. De-initialize submodules and force a clean clone with:
  65
  66    $ make deepclean
  67
  68 Workflow (ISO build)
  69 --------------------
  70 Parent build scripts require this mechanism to do some fingerprinting,
  71 so here is the intended flow for all artifacts to be generated right:
  72
  73 1. (Optional) Cached submodules might be fetched from build cache.
  74
  75 2. Submodules are updated
  76    We also dump each submodule's git info using repo_info.sh, since
  77    we want to collect git refs before patching (i.e. upstream refs).
  78
  79 3. Make target `release` is built
  80    This will make sure the modules are in a clean state, put them in cache,
  81    then apply the patches.
  82
  83 4. fuel-main's `${FUEL_MAIN_TAG}-opnfv-root` tag is used to determine VERSION info
  84    It will accommodate both bound tags and remote tracking references.
  85
  86 Sub-project maintenance
  87 -----------------------
  88 1. Adding a new submodule
  89    If you need to add another subproject, you can do it with `git submodule`.
  90    Make sure that you specify branch (with `-b`), short name (with `--name`)
  91    and point it to `upstream/*` directory, i.e.:
  92
  93    $ git submodule -b stable/mitaka add --name fuel-web \
  94      https://github.com/openstack/fuel-web.git upstream/fuel-web
  95
  96 2. Working with remote tracking for upgrading Fuel components
  97    Enable remote tracking as described above, which at `make sub` will update
  98    ALL submodules (fuel-main, fuel-library, ...) to remote branch (set in
  99    .gitmodules) HEAD.
 100
 101    * If upstream has NOT already tagged a new version, we can still work on
 102      our patches, make sure they apply etc., then check for new upstream
 103      changes (and that our patches still apply on top of them) by:
 104
 105    $ make deepclean patches-import
 106
 107    * If upstream has already tagged a new version we want to pick up, checkout
 108      the new tag in each submodule:
 109
 110    $ git submodule foreach 'git checkout <newtag>'
 111
 112    * Once satisfied with the patch and submodule changes, commit them:
 113      - enforce FUEL_TRACK_REMOTES to "yes" if you want to constatly use the
 114        latest remote branch HEAD (as soon as upstream pushes a change on that
 115        branch, our next build will automatically include it - risk of our
 116        patches colliding with new upstream changes);
 117      - stage patch changes if any;
 118      - if submodule tags have been updated (relevant when remote tracking is
 119        disabled, i.e. we have a stable upstream baseline), add submodules:
 120
 121    $ make deepclean sub && git add -f sub/*