How to send a good PR to the OpenMRS

OpenMRS JIRA Tickets — A complete work flow

Hello everyone, This is specially for the students and beginners who started working with OpenMRS.

Hope everyone is busy right now with GSoC proposals. Apart from that, I would like to share some basic learning about How to send a proper pull request(PR) to OpenMRS repositories.

First, I would like to share the advantages of a proper PR,

  1. If we are already reviewed carefully and send a proper PR, then we can reduce the time of the reviewers and other volunteers who spend so much of time to review our PR.
  2. Our PRs will be merged quickly with the main repository without any issues and we can start work on a other issue.
  3. It’s easy to manage the OpenMRS sprints and work flow through the actual tickets.
  4. Some of us forget to work on a PR again after the comments from the reviewers. So those PRs will be staged into that repository for a long time and finally, they will close it is without merging.
  5. We will be very happy if our PRs merged quickly. We can work on another issues with peaceful mind :-)

So the problem is How to send a proper PR? There might be different ways and different paths depending on the actual ticket information.

Select a ticket from the JIRA

  1. At the very first, you need to get the OpenMRS JIRA access. JIRA is an issue management application provided by the Atlassian. You need to get the access to the OpenMRS help desk. Once they approved your request, you will get an email and you can log in to their JIRA.
  2. Let’s go to the projects and explore the tickets. There are multiple ticket types based on the project type.
     a. Bug — The issues identified in the projects
     b. Enhancement — Improvements and enhancements for a concept or code
     c. New Feature — New features and ideas for the projects.
     d. Story — Continues stories for the development
     e. Task — Tasks and Sub Tasks for some larger tickets
  3. OpenMRS has some multiple ticket status to make the issue management easy. Those are,
     a. Need Assessment — Very first state of a ticket will be like this. The admin or higher level persons for that projects can only make this project for the works. We can’t claim the issue at this stage. We need until the assessment approved.
     b. Ready for Work — This is the second state of the tickets. At this stage any one can claim the issue for the work. 
     c. In Progress — This means, the ticket is on going and doesn't finish yet(claimed by some one for the work). 
     d. Code review — This means, the user who claimed the ticket is submitted the pull request to the repository and he needs the review before the merging. 
     e. Approved — The pull request for this ticket is approved and the required work for this ticket is completed by this time. 
     d. Closed — The ticket is closed for some reasons or the tickets can be closed after the required work done.
    e. Reopened — The issue can be reopened for the further changes. At that time, the ticket status will be Reopened.

Time to Claim a ticket

Let’s pick one ticket from the JIRA which has the own status as “Ready for Work”. You should claim the issue by pressing the “Claim Issue” button to work on the ticket.

Once you claimed the ticket, You will be automatically assigned as the ticket assignee, watchers and designated committer. Then the ticket status will be changed to “In Progress”.

Start to work on the ticket

Now the time to work on the assigned ticket. You should read the ticket information and the comments which are attached to that ticket. Those are the main key points for your work. If you have any issues or questions, let’s ask it through the JIRA or post it into the OpenMRS talk forum. Then someone will guide you to reach the target.

Make sure you have configured your IDE for OpenMRS coding standards. It will help you to write the codes according to their coding conventions. You can get more details about configuring the IDE for OpenMRS development from here,

These are some key points while you are working on a ticket,

  1. If you are working on a test case related ticket, you can use mvn -Dtest=<testClassName> test to compile and test only that class. If you try to compile everything after each modifications, It might take a lot of your time to complete.
  2. If you would like to compile without the test cases, you can do that using `mvn clean package -DskipTests or mvn clean install -DskipTests . It will skip the test cases while building the whole project.
  3. At the last, Please compile your whole project using mvn clean package or mvn clean package command. It will compile every think including the test cases of your whole project. (I recommend this method , then only you can ensure the test cases are not affected according your changes)

Let’s play with the code and everything to complete the work. Once you completed the work, please compile the whole project, and make sure the other related implementations are safe with your changes.

Commit your changes

Once you have completed your work on the local environment, you need to push your code to your GitHub to continue the process. Before committing your code to your repository, you need to think about their requirements for a Pull Request.

  1. You should create a new branch name which is equal to the ticket id. 
    Eg : If you have claimed an issue called “TRUNK-5068 Fix Test Cases”. Then your branch name should be “TRUNK-5068”
    Tips : You can use
    git branch <branch-name> to create a new branch, then use git checkout <branch-name> to move that branch.
  2. Then commit your changes to that created branch.
    Tips : You can use git add --all to add all the changed files to the git staging or you can use git add <file-name-with-path> to add only that changed file to the fit staging.
    Then you can use
    git commit -m <commit-message> to commit your changes.
  3. You should include one commit inside a Pull Requests. PRs with the multiple commits will not be accepted for the merging. So if you have more than one commits inside your PR, you should squash them into one commit.
    Tips : You can use git rebase --abort to get back to where you started with. Then use git rebase --interactive HEAD~2 to squash your last commit with previous one. You can get more information from here.
  4. Now the time to push your codes to the GitHub. Before that you should ensure, your local repository contains all the changes in the GitHub repository up to that time. You can use git pull <repo-url> to pull the latest changes to your local git environment.
  5. Finally you should push your local changes to the GitHub. Once you pushed your changes, you can see a new alert about the pull request to the parent repository in your repository dashboard. You can use git push <repo-url> <branch-name> or git push origin <branch-name> to push your changes. you may be required to enter your user name and password before pushing the changes.
    If you squash your commits, then you need to use git push -f <repo-url> <branch-name> to push your changes.

Let’s create the Pull Request

Now the time to create your Pull Request to the parent repository under the OpenMRS organization. You should care about this stage because you are going to show them that you have done something to merge with OpenMRS.

You should create the pull request,
 From : Your Repository and Branch : Created branch (eg : 
 TRUNK-5068)
To : Repository under the OpenMRS : Master branch.

While you are creating the pull request, You need to give a pull request title. The pull request title should be contain the ticket id at the first with the summarized title. Then you will be required to follow the pull request template. Most of the OpenMRS repositories are already configured with pull request templates. So you just want to update the required information to that pull request template. You should include the ticket information along with the description.

There might be some GitHub plug-ins which will evaluate your work and the code quality to reduce the reviewers work on your PR. It might take several minutes to complete the required actions. Once it completes, you can see the results below the PR description.

Request Code Review

Once you have sent a PR to OpenMRS repository, you need to change your ticket status from “In Progress” to “ Code Review (Initial)”. It will indicate to the project administrators and reviewers about the request for the review. So they will review and provide their comments to improve your work.

If they give any comments or suggestions for your pull request, then you need to fix those issues or you need to work on that ticket again. Then you need to commit your new changes and squash to one commit before pushing to the repository. The new changes of that branch will be automatically added to the existing PR for the review.