How to contribute

Before you submit your first pull request please read and agree to the iCLA.

Preparation

Every change to the code is tracked by an issue in JIRA; without an issue, code will not be reviewed, and without review, code will not be accepted. To avoid duplication, search for an existing issue about the change, and if none exists, file a new one. Most of the communication about code changes takes place in the issue, so be sure that the issue describes the exact problem being solved.

The issue workflow is part of the Development Process.

The person who is working on an issue should be the "assignee" of that issue in JIRA.

Creating a Branch

Each pull request should represent a single complete change, so you should separate distinct changes into multiple pull requests.

Its probably easiest if you create a new 'topic' branch on your forked repository for each unique piece of work rather than commit changes directly into master or our special develop branch. Why?

It means you can work on something very specific, get it up to date and send a 'pull request', To move on to a seperate piece of work, you simply create a different branch. It might also make it easier to keep up to date with the openMF/mifosx repository as explained in next section.

Pull in changes

There will be development changes to the openMF/mifosx almost every day for the foreseeable future so its important to keep your fork of the software up to date with the latest changes.

To pull in upstream changes from repository you forked revisit the section "Keep up to date" form the build instructions.

After you pulled all changes from upstream you need to rebase your topic branch with the latest code.

If you are ready push your topic branch to your GitHub account.:

Testing

All changes must be tested.

In most cases, an integration test is required for every change to the code. In some cases where it is not possible to write an integration test, manual tests are used. If the change was tested manual a detailed step by step description on how to redo the test should be added to the issue at JIRA.

Based on the complexity of the business logic unit tests are required.

Ensure that the change has not caused regressions by running the integration test suite locally. See Build Instructions for more details.

Review

Thorough code reviews are one of Mifos' ways of ensuring code quality. Every pull request must be reviewed by the module owner of the code or one of their designated peers. Pull requests which cross modules, change APIs, or have security-related changes must have an additional review by one of the members of the core team.

Creating a Pull Request

We would expect people to use the Fork & Pull model for collaborating back. Simply this means that we expect you to use GitHub tools here and to send pull-requests to us when you have a piece of work you want to contribute back.

Read more here: https://help.github.com/articles/using-pull-requests.

Before sending out a pull request, please ensure that the following pre-requisites are taken care of:

  1. API documentation has been updated to reflect any changes made to the API (new API's, adding new Fields or Options to existing API etc)

  2. Any relevant database changes are encapsulated in an SQL file with the next available version number.

    1. These patches are automatically applied by Flyway on server start up.

    2. For any modifications to the schema which affects data on existing installations (Ex: moving columns to new table etc), ensure that the upgrade scripts are also accompanied by data migration scripts in the same patch file.

  3. An integration test is added/updated to test the new feature developed/bug-fix being madec

  4. The pull request has a JIRA issue associated with it.

  5. The Relevant JIRA number (Ex: MIFOSX-1454) is present as a part of the commit message.

  6. Newly added code has been formatted and cleaned up as per our Mifos Coding Style Guide.

  7. Comments are added where relevant to ease peer review.

  8. Your work is present in a single commit rather than several broken up commits.

  9. Your work is rebased on top of the latest code from develop branch to make life easier for our committers.

  10. All newly added files contain a license header.

    1. To ease the creation of license headers, run the following command: