[Jclouds Wiki] Update of "PromoteProvider" by IgnasiBarrera

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Jclouds Wiki" for change notification.

The "PromoteProvider" page has been changed by IgnasiBarrera:
https://wiki.apache.org/jclouds/PromoteProvider

New page:
= Promote a provider to the main repo =

This guide proposes a workflow to promote a provider to the main jclouds repository. The goals of these steps are:

 * Keep the commit history from the old repo.
 * Move the code to the right folder in the new repo.
 * Be able to work with the main repo normally: being able to merge, rebase, etc, without issues.

The original tutorial can be found at: https://www.vlent.nl/weblog/2013/11/02/merge-a-separate-git-repository-into-an-existing-one/

== Promotion example: Chef ==

To illustrate the process we'll see how the [[https://github.com/jclouds/jclouds-chef|jclouds-chef]] repository can be merged. We want to merge it keeping the main repository structure, so we have to move:

 * jclouds-chef/core -> jclouds/apis/chef
 * jclouds-chef/enterprise -> jclouds/providers/enterprisechef

To do this, there are several steps required.

=== Clone the repositories ===

{{{
cd /tmp
git clone https://git-wip-us.apache.org/repos/asf/jclouds.git
git clone https://git-wip-us.apache.org/repos/asf/jclouds-chef.git
}}}

=== Isolate each folder to promote to its own branch ===

First thing to do is to isolate each folder to be moved to its own branch, and also moving it to the directory where it will be placed once merged. This can be done using `git filter-branch` as follows:

{{{
# Create a branch that only contains jclouds-chef/core
cd /tmp/jclouds-chef
git checkout -b only-core
git filter-branch --index-filter \
  'git ls-files -s | sed "s-\t\"*-&apis\/chef/-" | GIT_INDEX_FILE=$GIT_INDEX_FILE.new \
  git update-index --index-info && mv "$GIT_INDEX_FILE.new" "$GIT_INDEX_FILE"' --subdirectory-filter core/ HEAD

# Create a branch that only contains jclouds-chef/enterprise
git checkout master
git checkout -b only-enterprise
git filter-branch --index-filter \
  'git ls-files -s | sed "s-\t\"*-&providers\/enterprisechef/-" | GIT_INDEX_FILE=$GIT_INDEX_FILE.new \
  git update-index --index-info && mv "$GIT_INDEX_FILE.new" "$GIT_INDEX_FILE"' --subdirectory-filter enterprise/ HEAD
}}}

'''IMPORTANT NOTE''': In the `filter-branch` command we are doing two things: filtering only the contents and history of the files in the directory specified by the ''subdirectory-filter'' parameter,  and moving them to the folder where they will land once merged in the main repo (specified in the ugly `sed` command).

=== Merge the branches into the main repo ===

At this point we have the `jclouds-chef` repo with two branches that contain each folder to be merged in the main repo, already with the right directory structure, and keeping the commit history. Now we just have to merge those branches into the main repo as follows:

{{{
cd /tmp/jclouds

# Add the repository with the filtered branches as a remote (the -f parameter will make git automatically fetch the branch info)
git remote add -f chef ../jclouds-chef/

# Merge the branches
git merge chef/only-core
git merge chef/only-enterprise

# Remove the remote, as it is no longer needed
git remote rm chef
}}}

And that's it! Now the main repository will have the `jclouds-chef` folders merged in the right directories, and every file should keep its commit history. Review the changes, and push!