Submitting Patches

CommCare and CommCare Android are open source projects and are available under the Apache 2.0 license.

In order to submit patches, contributors must sign an agreement, in which they give over their copyright to the foundation that manages the licensing of the project. These agreements are available for Individuals and Corporations. Agreements are required before patches are approved.

All new code submitted to the CommCare/CommCare Android project must be code reviewed and approved by the project's core committers. The process is as follows. (Note that this is written for the commcare-core repository, but the process is the same for the commcare-android repository).

Outdated, should be updated to reflect git

1. A developer clones https://github.com/dimagi/commcare-core or https://github.com/dimagi/commcare-android and makes changes to the code base.

• cloning trunk: git clone https://github.com/dimagi/commcare-core;

• editing files: vi MyClass.java;

• adding useful message: git commit -m "Changing MyClass";

2. Once the developer finished development, they must prepare the code for review. If there are new files, you must merge and commit the changes. If there are conflicts, they must be resolved.

• ensuring latest files from trunk: git clonehttps://github.com/dimagi/commcare-core;

• if there are new files, merge and commit changes: git merge; git commit -m "Merging new files";

• if there are conflicts, edit the files and resolve:

vi MyClass.java;
git resolve -m MyClass.java;
git commit -m "Resolving conflicts";

3. Push the patch to https://github.com/dimagi/commcare-core. It must be a singular revision on the 'master' branch and you must try to create a remote head. For reasons explained below, your code will be automatically rejected if you do not follow these rules.

Assuming repo is up to date, create remote head and push only one revision: git push -f -r default https://github.com/dimagi/commcare-core

Ensure you are up to date. You must merge with the latest code from trunk before submission. 

Use the 'master' branch. This is Git best practice and it prevents trunk from being polluted. 

Create remote heads. Every patch currently under review is a separate head in this repository so patches do not block. Use the -f switch on the command line or the force push checkbox in TortoiseHg. 

Push one revision at a time. This protects against accidentally pushing code that is not meant for review. Use the -r switch on the command line or the target revision field in TortoiseHg. 

The code can only advance one head at a time. If you have unrelated patches on multiple heads, push them separately. 

4. Once the new code is accepted, it is available in https://bitbucket.org/commcare/commcare/commits/all. An automated email will be sent to core committers notifying them of the new patch.

5. The reviewer may recommend changes which must again be pushed into https://bitbucket.org/commcare/commcare for more review. Once the reviewer is satisfied, they will approve the patch.

6. The patch will be tagged and the code will automatically be moved into https://bitbucket.org/commcare/commcare