Submitting pull requests

This document details out the steps / best practices for submitting a pull request / bug fixes / feature enhancements to Bahmni codebase. Since all Bahmni code, is hosted on Github, and is open source, we follow the commonly used pull-request model for submitting patches / changes to Bahmni code base. Related reading:

If you are new to Git/Github, please check out this video to understand Git/Github better:

High Level Steps

  1. JIRA: Please ensure the pull request, is for an existing JIRA card. If the card does not exist, create it. Please refer here for pointers on how to write an effective JIRA card.  
    • When you create a ticket, the state would be "Needs Assessment", or "Backlog". Usually, someone would assess it, and change the state to "Ready For Dev". You may raise relevant questions using discussion forums like talk or PAT calls. 
    • When you are ready, claim the card by assigning to yourself, and changing state to "In Development"
  2. FORK: Fork the repository that you wish to make changes into your own Github Account. Once you fork a repo, then you are free to make any changes to that repository, since all changes go to your forked repository. 
  3. BRANCH: Create a branch for your bug-fix (or feature) on your forked repository. For instance, if you are working on card number #546, then you can maybe create a branch called: "bug-546". Creating your own branch, ensures that you can work on other items simultaneously, and it also allows your master to stay in sync with the remote master.
  4. WORK: Work on your branch, create commits with good commit messages which explain why you made a certain change. Ensure that you mention the Mingle card number in the commit message. 

    It is important that your github email address is registered in your local git configuration, to ensure the right email address is associated with your commits. This is required to ensure the CLA below is signed against the right contributor/email address. To set your github associated email address in git run this command: `git config --global ""`

  5. (optional) SQUASH: Once you feel your branch has all the commits you need, and is tested, and ready, you may want to Squash your commits into ONE, or as few as possible. This helps the reviewer in understanding what changed for the fix, and creates a clean commit history, when your branch is merged into the main line. You can use the git command line, or a UI tool to squash commits. (Github also let's the reviewer "squash and merge," so this step is not strictly necessary.)
  6. UPDATE: If you have been working on your branch for some time, it is likely that your master and your branch are both out of date from the original repository. Its a good idea to pull the latest changes from the main repository, so that you are sure, that your changes work on the latest code base too. Please read this link to understand how to update your fork with the latest codebase. After you have updated your local master, please also remember to update your branch
  7. PUSH: Push your branch commits to your fork on Github. 
  8. PULL REQUEST: Submit a pull request from Github for your branch. Provide a good comment on what work you did, and any other screenshots / information you would like the reviewer to know. Once you submit a pull request, the Bahmni Team automatically receives an email with the link to a pull request.
    • Pull against master: By default, create pull requests on master branch, unless the ticket description or comments specifically say otherwise, or such is agreed in discussions. The reviewer will take care of back porting changes to other branches, as needed. The relevant Jira card needs to specify all the fix versions (release versions) where the PR needs to be applied. 
    • Refer the JIRA card in PR: The summary/title of the pull request should contain the JIRA card number e.g 'BAH-763'
    • Update JIRA card: Update card with the PR link(s), also change workflow status to "Needs Code Review"
  9. SIGN THE CLA: The first time you submit a pull request to any Bahmni repository, an automated tool called CLA assistant will ask you to sign a CLA. (Read more about the Contributor License Agreement.)

If you already opened a pull request, but wish to send some more changes, you can commit & push code to the same branch, and the pull request gets updated. If you feel, you want to temporary hold off a pull request, you can "close" the pull request with a comment, and send a new pull request from the same branch again later in time.

On this page:

The Bahmni documentation is licensed under Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)