Git Merging
Merge pull request with the Merge Pull Request button on GitHub
After the pull request is reviewed and approved, you are good to merge it to the main repository. If it is a small change and you feel confident that there is NO need to run tests before applying it you can use the Merge Pull Request button on GitHub. After you do that you must observe the CI closely to make sure that the merge did not break the build. If it is the case, you are responsible for fixing the build as soon as possible meaning you cannot ask the contributor to do it (unless it's you)
Merge pull request with rebase
After the pull request is reviewed and approved, you are good to merge it to the main repository. Our intention is to keep the history of our main repository linear so we will be avoiding merge commits and using rebase instead. It also means that we will only use the github merge button for simple changes which does not require running tests.
The rebase should not be used if someone specifically asked not to do so. It is for rare cases when more work is based on changes from the pull request (e.g. when someone maintains own version of code regularly merging from the main repository and contributing back). See Merge branches developed in parallel to our repository.
To save some key hits we recommend to setup an alias for 'pull --rebase' by running
git config --global alias.up "pull --rebase"
From now on you will be able to use 'git up upstream master' instead of 'git pull --rebase upstream master'.
- Update your master.
git checkout master git pull --rebase upstream master
- Go to the pull request page on github.com and find i on the left from the Merge pull request button.
- Copy anything after 'git pull' in a command from Step 2 which you will find after clicking the tiny i.
- Fetch from the pull request to a new branch you'll create.
Replace BRANCH_YOU_WANT_TO_CREATE with something like TRUNK-123. This feature branch will be created in your repo for the pull request.
git fetch https://github.com/...pasted_from_previous_step:BRANCH_YOU_WANT_TO_CREATE
- Checkout the branch.
git checkout TRUNK-123
- Update the branch to the latest master.
git pull --rebase upstream master
- If there are conflicts see the Resolve conflicts section.
- Run tests.
mvn clean install
- If tests fail, ask for changes on the pull request in github. Discard the branch.
git checkout master git branch -D TRUNK-123
- If tests pass:
- Check status to make sure that code was properly formatted and there are no modified files, otherwise commit them.
git status
- Review changes between the latest master and the branch.
git diff master..
- Verify that the log is clean.
Use rebase to correct if needed. Most of tickets should be one commit only, especially bug fixes. They are faster to back port and track.
git log master..
It will let you rebase commits from the pull request to the most recent master.git rebase -i master
Do not ever attempt to change commits that have already been pushed to the main repository!
- Check status to make sure that code was properly formatted and there are no modified files, otherwise commit them.
- If tests fail, ask for changes on the pull request in github. Discard the branch.
- Checkout your master and merge changes
git checkout master git merge TRUNK-123
- Push changes to the upstream master and your fork
If Git warns you that the push is impossible, it is most likely due to the fact that someone has pushed other changes and you need to pull again. Go back to 5.
git push upstream master git push
If even though you pulled and Git does not want to push, it means you have accidentally modified some commits which are already in the repository. Under no condition try to overwrite the history in the main repository. Discard the changes and start over again. - Discard the merged branch.
git branch -D TRUNK-123
- Say thank you and close the pull request if it was not closed automatically.
Merge your work
If you have push rights to the main repository, you do not need to use pull requests to merge your changes.
- Checkout the branch you want to merge
git checkout TRUNK-123
- Update the branch to the latest.
git pull --rebase upstream master
- Run tests.
mvn clean install
- Checkout your master and merge changes
git checkout master git merge TRUNK-123
- Push changes to the upstream master and your fork.
git push upstream master git push
- Discard the merged branch.
git branch -D TRUNK-123
Resolve conflicts
It may happen that a merge fails, due to conflicts. You can first try using a different merge strategy such as patience.
git rebase -X patience master
If that fails you need to look through conflicting files and edit them manually. If you do not want to edit a file manually you, but use "theirs" or "ours" version of the file run:
git checkout --theirs path/to/file
or
git checkout --ours path/to/file
When you are done you need to stage and commit the changes.
git add -A git commit -m "TRUNK-123: Resolving merge conflicts"
You can now rerun rebase.
Merge OpenMRS repository branches
Feature branches stored in the main repository are designated for bigger features on which we want to work collaboratively. They should be merged back to the master branch with a real merge and not through rebase. Developers can safely base their work on branches stored in our main repository.
When working on public feature branches you should remember to do a merge once in a while from the master branch. A good practice is to pick one person responsible for keeping the branch up to date with the master branch. Such updates should only happen when important changes are committed to the master branch. The feature branch should only be merged to the master branch when it is complete or in a stable state.
Merge branches developed in parallel to our repository
Currently, we do not collaborate with any team that develops OpenMRS in a separate fork, but wants to contribute to our repository. We are open to setting up a workflow for such a case without rebasing, but actual merges if desired.