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.
+