build: Use git submodules for Fuel git repos

This change reworks support for cloning (fetching) and patching all
Fuel components (fuel-library ... fuel-ui, see [1] for full list),
both outside the ISO build process (for development purposes, like
testing OPNFV patches apply cleanly to each component), and during
the ISO build.

The implementation relies heavily on git submodules and patches,
so backporting pending upstream gerrit changes, as well as adding new
out-of-upstream-tree patches, should be trivial.

Also, since without tracking remotes the repos rarely change, leverage
the in-place OPNFV build caching mechanism to drastically reduce the
number of git clones during each build.

The mechanism is detailed more in-depth in the JIRA ticket [3], and
it's merely a rehash of the submodule handling in Armband, implemented
initially by Stanislaw Kardach <stanislaw.kardach@cavium.com>.

Pros (+ new features):
 - OPNFV patches for Fuel components can be applied (imported) or
   developed (exported) outside of the ISO build process;
 - git repo caching reduces the number of external pulls;
 - reuse the same fuel-* componets in ALL targets
   e.g. fuel-mirror used to employ 2 slightly different git trees;
 - one step closer to Fuel/Armband merge (lots of steps left though);

Cons:
 - adds a lot complexity to solve a non-problem (handling the repos
   is fine in the current form, for the current goals);
   However, patching <fuel-astute> or <fuel-agent> seems to be
   quite complicated with the current mechanism, as env vars
   override our locally patched repos for these components).
   The proposed change should eliminate this issue completely.

CHANGE:
 Aligned divergent fuel-mirror in ISO vs local repo build by
 applying the 302 redirect fix ("Fixed handling http redirects") [2]
 on top of 9.0.1 tag in fuel-mirror repo, and using that for both.
 This obsoleted the followking mk file:
 - build/f_isoroot/f_repobuild/config.mk

CHANGE:
 Removed unused make target `get-fuel-repo` from build/config.mk.

FIXME:
 Remote tracking is currently deactivated for all branches.
 Change this when remote HEAD should be tracked instead,
 e.g. during Newton rebase.

[1] https://github.com/openstack/fuel-main/blob/stable/mitaka/repos.mk#L32
[2] https://review.openstack.org/#/c/334882/
[3] https://jira.opnfv.org/browse/FUEL-200

TODO: Extend build/f_repos/README.md with info about:
 - branch changes;
 - tag bumps;
 - patching now supports subdirs;

v5 -> v6:
 * Added support for nesting patches in subdirs, to be used for feature
   groups and related changes across submodules.
   E.g. Upcoming multiarch EFI support could go in:
    - .../f_repos/patch/fuel-agent/multiarch-efi/...;
    - .../f_repos/patch/fuel-astute/multiarch-efi/...;
   While Armband patches could go in:
    - .../f_repos/patch/fuel-agent/armband/...;
    - .../f_repos/patch/fuel-astute/armband/...;
   etc.
v6 -> v13:
 * fix wrong tag used for VERSION dump;
 * fix wrong tag used for patches-export;
 * move OPNFV_TAG to main config.mk and use it in FUEL_*_COMMIT;
 * only run `patches-import` when patches changed / not yet applied;
 * only run `clean` for stale `.cacheid` (avoid re-applying patches);
 * allow git submodule path/name to be different (FIXED);
 * put-cache should only run when artifact is not already cached;
 * `git am`: use 3-way merge so already applied patches are gently
   skipped (useful for upstreaming patches from Armband);
 * Properly support nested patch dirs;
 * Colorize the output a little;

JIRA: FUEL-200

Change-Id: I9dbdd9b3022896d4497d21be8dacc859730db489
Signed-off-by: Alexandru Avadanii <Alexandru.Avadanii@enea.com>

1 files changed, 94 insertions, 0 deletions

diff --git a/build/f_repos/README.md b/build/f_repos/README.md
new file mode 100644
index 000000000..6cc825e05
--- /dev/null
+++ b/build/f_repos/README.md
@@ -0,0 +1,94 @@
+Fuel@OPNFV submodule fetching and patching
+==========================================
+
+This directory holds submodule fetching/patching scripts, intended for
+working with upstream Fuel components (fuel-library, ... , fuel-ui) 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;
+
+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;
+
+Workflow (development)
+----------------------
+The standard development workflow should look as follows:
+
+1. Decide whether remote tracking should be active or not:
+   NOTE: Setting the following var to any non-empty str enables remote track.
+   NOTE: Leaving unset will enable remote track for anything but stable branch.
+
+   $ export FUEL_TRACK_REMOTES=""
+
+2. All Fuel sub-projects are registered as submodules. To initialize them, call:
+   If remote tracking is active, upstream remote is queried and latest remote
+   branch HEAD is fetched. Otherwise, checkout commit IDs from .gitmodules.
+
+   $ make sub
+
+3. Apply patches from `patches/<sub-project>/*` to respective submodules via:
+
+   $ make patches-import
+
+   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`;
+
+4. Modify sub-projects for whatever you need.
+   Commit your changes when you want them taken into account in the build.
+
+5. Re-create patches via:
+
+   $ make patches-export
+
+   Each commit on `opnfv-fuel` branch of each subproject will be
+   exported to `patches/subproject/` via `git format-patch`.
+
+   NOTE: Only commit (-f) submodules when you need to bump upstream ref.
+   NOTE: DO NOT commit patched submodules!
+
+6. Clean workbench branches and tags with:
+
+   $ make clean
+
+7. De-initialize submodules and force a clean clone with:
+
+   $ make deepclean
+
+Workflow (ISO build)
+--------------------
+Parent build scripts require this mechanism to do some fingerprinting,
+so here is the intended flow for all artifacts to be generated right:
+
+1. (Optional) Cached submodules might be fetched from build cache.
+
+2. Submodules are updated
+   We also dump each submodule's git info using repo_info.sh, since
+   we want to collect git refs before patching (i.e. upstream refs).
+
+3. Make target `release` is built
+   This will make sure the modules are in a clean state, put them in cache,
+   then apply the patches.
+
+4. fuel-main's `${FUEL_MAIN_TAG}-opnfv-root` tag is used to determine VERSION info
+   It will accommodate both bound tags and remote tracking references.
+
+Sub-project maintenance
+-----------------------
+1. 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`)
+   and point it to `upstream/*` directory, i.e.:
+
+   $ git submodule -b stable/mitaka add --name fuel-web \
+     https://github.com/openstack/fuel-web.git upstream/fuel-web