From 1636afb0aa187eb899f71b0abbd4d67aa647a429 Mon Sep 17 00:00:00 2001 From: Misty Stanley-Jones Date: Thu, 2 Oct 2014 15:25:24 +1000 Subject: [PATCH] HBASE-11998 Document a workflow for cherry-picking a fix to a different branch --- src/main/docbkx/developer.xml | 137 ++++++++++++++++++++++++++++++++-- 1 file changed, 130 insertions(+), 7 deletions(-) diff --git a/src/main/docbkx/developer.xml b/src/main/docbkx/developer.xml index 322483451a6..382367f5717 100644 --- a/src/main/docbkx/developer.xml +++ b/src/main/docbkx/developer.xml @@ -1872,14 +1872,27 @@ justification="I know what I'm doing") git format-patch is preferred because it preserves commit messages. Use git squash first, to combine smaller commits into a single larger one. + + Do not use --no-prefix, even if you were in the + habit of doing it previously. + - git format-patch --no-prefix origin/master --stdout > HBASE-XXXX.patch + git format-patch origin/master --stdout > HBASE-XXXX.patch - git diff --no-prefix origin/master > HBASE-XXXX.patch + git diff origin/master > HBASE-XXXX.patch + If your branch is based upon a different remote branch, replace + origin/master with the remote to + compare against. + If you are new to creating patches, it's a good idea to check out + a fresh branch and try to apply your patch to it. If you used + git format-patch, apply the patch using + git am. Otherwise, use git + apply. If the patch does not apply correctly, fix the + problem and try again. @@ -1890,7 +1903,9 @@ justification="I know what I'm doing") Make sure you review and for code style. + linkend="common.patch.feedback"/> for code style. If your patch was + generated incorrectly or your code does not adhere to the code formatting + guidelines, you may be asked to redo some work.
@@ -2037,15 +2052,123 @@ justification="I know what I'm doing") Include the Jira issue id in the commit message, along with a short description of the change and the name of the contributor if - it is not you. Be sure to get the issue id right, as this causes - Jira to link to the change in Subversion (use the issue's + it is not you. Be sure to get the issue ID right, as this causes + Jira to link to the change in Git (use the issue's "All" tab to see these). + + Commit the patch to a new branch based off master or other + intended branch. It's a good idea to call this branch by the JIRA + ID. Then check out the relevant target branch where you want to + commit, make sure your local branch has all remote changes, by doing + a git pull --rebase or another similar command, + cherry-pick the change into each relevant branch (such as master), + and do git push <remote-server> + <remote-branch>. + + If you do not have all remote changes, the push will fail. If + the push fails for any reason, fix the problem or ask for help. + Do not do a git push --force. + + Before you can commit a patch, you need to determine how the patch + was created. The instructions and preferences around the way to + create patches have changed, and there will be a transition + periond. + + Determine How a Patch Was Created + + If the first few lines of the patch look like the headers + of an email, with a From, Date, and Subject, it was created + using git format-patch. This is the + preference, because you can reuse the submitter's commit + message. If the commit message is not appropriate, you can + still use the commit, then run the command git + rebase -i origin/master, and squash and reword + as appropriate. + + + If the first line of the patch looks similar to the + following, it was created using git diff + without --no-prefix. This is acceptable too. + Notice the a and b in + front of the file names. This is the indication that the + patch was not created with --no-prefix. + diff --git a/src/main/docbkx/developer.xml b/src/main/docbkx/developer.xml + + + If the first line of the patch looks similar to the + following (without the a and + b), the patch was created with + git diff --no-prefix and you need to + add -p0 to the git apply + command below. + diff --git src/main/docbkx/developer.xml src/main/docbkx/developer.xml + + + + Example of Committing a Patch + One thing you will notice with these examples is that there + are a lot of git pull commands. The only + command that actually writes anything to the remote repository + is git push, and you need to make absolutely + sure you have the correct versions of everything and don't have + any conflicts before pushing. The extra git + pull commands are usually redundant, but better + safe than sorry. + The first example shows how to apply a patch that was + generated with git format-patch and apply it + to the master and branch-1 branches. + + The directive to use git format-patch + rather than git diff, and not to use + --no-prefix, is a new one. See the second + example for how to apply a patch created with git + diff, and educate the person who created the + patch. + $ git checkout -b HBASE-XXXX +$ git am ~/Downloads/HBASE-XXXX-v2.patch +$ git checkout master +$ git pull --rebase +$ git cherry-pick <sha-from-commit> +# Resolve conflicts if necessary or ask the submitter to do it +$ git pull --rebase # Better safe than sorry +$ git push origin master +$ git checkout branch-1 +$ git pull --rebase +$ git cherry-pick <sha-from-commit> +# Resolve conflicts if necessary +$ git pull --rebase # Better safe than sorry +$ git push origin branch-1 +$ git branch -D HBASE-XXXX + + This example shows how to commit a patch that was created + using git diff without + --no-prefix. If the patch was created with + --no-prefix, add -p0 to the + git apply command. + $ git apply ~/Downloads/HBASE-XXXX-v2.patch +$ git commit -m "HBASE-XXXX Really Good Code Fix (Joe Schmo)" -a # This extra step is needed for patches created with 'git diff' +$ git checkout master +$ git pull --rebase +$ git cherry-pick <sha-from-commit> +# Resolve conflicts if necessary or ask the submitter to do it +$ git pull --rebase # Better safe than sorry +$ git push origin master +$ git checkout branch-1 +$ git pull --rebase +$ git cherry-pick <sha-from-commit> +# Resolve conflicts if necessary or ask the submitter to do it +$ git pull --rebase # Better safe than sorry +$ git push origin branch-1 +$ git branch -D HBASE-XXXX + + Resolve the issue as fixed, thanking the contributor. Always set the "Fix Version" at this point, but please only set a - single fix version, the earliest release in which the change will - appear. + single fix version for each branch where the change was committed, + the earliest release in that branch in which the change will appear. +