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.

1. 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'.

2. 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:

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.

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.

The criteria used for determining whether we should backport something is generally:

• Someone has requested a backport of a feature.

• Backporting the feature will not break any existing data or require any changes at an implementation level.

• Backporting the feature allows us to enable something that is otherwise not possible or fixes behaviour that is obviously a bug.

• It seems unlikely that backporting the feature will require any changes to any modules, other than to take advantage of any new functionality.

The goal is to ensure that if someone is already running a version and we release a maintenance version of it, they only have to upgrade the version of core and everything else will continue working, while still allowing us to add new features to an existing version when those features are useful (so, a much looser interpretation of SemVer than we use on the frontend).