Git Backporting

The main "master" branch in the openmrs-core project contains the latest in-progress code. All new features and bug fixes should be committed there first.

There are 1.9.x, 1.8.x, 1.7.x, etc branches that represent code that will go the next point release in that line. Those branches were created off of master when the 1._.0 alpha was released. (e.g. 1.9.x was created and was the same as master when 1.9.0 alpha was released.)

When a bug is fixed in master that should also be fixed in the next 1.9 release, that bug is to be "backported" to 1.9.x branch. The simple definition of a backport is just committing a patch (or commit) to the 1.9.x branches that was already committed to master. Commits can be backported by

Backporting on GitHub:

The method of choice is called cherry picking.

Find the commit you want to backport.
- Browsing GitHub is the easiest method. e.g. This commit on master is what I want.
- The command line way is fairly easy as well. This command will show the last 3 commits on master:
```
git checkout master
git clean -df
git pull --rebase upstream master
git log -3
```
  'git clean -df' is an optional command which removes all untracked files which are left over from the previously checked out branch. This command is a good habit, because it helps to avoid accidentally adding such files to the index with 'git add -A'.
The commit hash we want is efe907df91596c3eff4cc2eb80ee2bbe09d1f373. (We can shorten this and use just efe907. -x means "add some text pointing to the original commit")
```
git checkout 1.9.x
git clean -df
git pull --rebase upstream 1.9.x
git cherry-pick -x efe907
git push upstream 1.9.x
```
- the resulting backport can be seen here on the 1.9.x branch.

Cherry-picking merge commits

Note: if the commit that you tried to cherry-pick was a merge commit, you may get an error message like:

git cherry-pick -x de7fd1bd259ebb7ab95eb18659cbb19fd680cd3e
fatal: Commit de7fd1bd259ebb7ab95eb18659cbb19fd680cd3e is a merge but no -m option was given.

In this case you should look at the commit you're trying to backport and determine which of its two parents is the commit right before the one you are cherry-picking. Assuming it's the first one (they are listed in a consistent order on github, or using git show), you would add "-m 1" to the prior command, e.g.

git cherry-pick -x de7fd1bd259ebb7ab95eb18659cbb19fd680cd3e -m 1

fatal: bad object errors

When cherry picking, you may some times get this error: fatal: bad object xxxxxxxxxxxxxxxxx, where the x stand for the commit hash.

You need to fetch the latest changes from upstream master so that the commit you want to cherry-pick is in your local repo. "git fetch --all" should do the trick.

For instance, i got the above error when cherry picking some master commits into the 1.11.x branch. Switching back to the master branch, then do git pull --rebase upstream master, before switching back to the 1.11.x branch to try again, is all i needed.