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.
```
git fetch https://github.com/...pasted_from_previous_step:BRANCH_YOU_WANT_TO_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.
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.
    git log master..
    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 rebase -i master
    It will let you rebase commits from the pull request to the most recent master.
    
    Do not ever attempt to change commits that have already been pushed to the main repository!
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
```
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.
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.