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