Code submission process

Here's a summary of the basic steps to follow when submitting a patch or doing a commit:

1. Do an update from the code repository to make sure you have the latest code
2. Write the tests for your code (or identify the existing tests that exercise code you will be changing)
3. Write your code
4. Make sure the tests that exercise your code all pass
5. Do an update from the code repository to get any changes that may have been committed since you started your work (and resolve any conflicts or compilation issues)
6. Run the ant build target "run_test" using the build.xml file (this will run the entire ApplicationTestSuite) and verify that the build succeeds (meaning there are no test errors/failures)
7. Create and submit your patch or commit your changes

Modifications done to the Mifos repository for bug fixing / feature enhancements have to be submitted as a patch. This patch should include all the changes done by the developer as part of the bug fixing / feature enhancements.

All code written for Mifos should be accompanied by associated unit tests. If you are writing a new feature, be sure to write unit tests that exercise the new functionality being implemented. If you are fixing a bug, write a unit test that fails because of the bug before you fix the bug. After you fix the bug, your unit test should pass. Include all the unit tests you write as part of your patch.

Prior to submitting a patch or checking in code, you are required to run the test suite locally on your machine to ensure that all tests pass. You can do this by running the ant build target "run_test" using the build.xml file located at the top level of the project. This can be run either from the command line or from within Eclipse. It takes approximately 30 minutes to 1 hour to run through the entire test suite (depending on the hardware you are running on). Only then should you check-in your code or submit your patch. If you're checking in code, you can confirm that your check-in didn't break the build by looking at our build server (see "Builds" at mifos.sourceforge.net).

How to generate a patch

The local workspace has to be synchronized with the repository to resolve conflicts if any, before the patch is created. Also the build is to be run ensuring all the test cases pass along with the testing of the fix after deployment. The patches can be created by using the subversion plug-in for the Eclipse IDE. This internally runs the svn diff command to get all the modified files comparing the local workspace against the repository. Patches can also be created by running the svn diff command through the svn prompt and re-directing the output to a file.

All changes necessary to address a bug fix / feature enhancement should be present within a single patch file. Along with the changes done to the source code, the patch should also contain the modifications done if any to testcases, database scripts, struts-config etc. The patch creation is to be done from the project directory so as to include all the changes done for the fix. Do not include in your patch local changes to configuration files (generally the easiest way to do this is to edit my.build.properties instead of build.properties, and so on).

To create a patch through Eclipse plug-in: Select the workspace(project) which contains the modifications to be included in the patch. >From the popup menu, select Team > Create Patch.... The Create Patch wizard will open.
Choose where the patch should be saved: Save to File System - this will place the patch in the specified file in the local file system Click Next to configure how the patch is generated. Choose how to configure the patch: Recurse into sub-folders - If disabled, only the direct children of the selection which have undergone modification are included in the patch. Otherwise, all descendants which have undergone modifications are included. (this option is by default enabled, and should remain checked to ensure all the changes are present as part of the patch) New files added: In case new files have been added, this would get indicated as an unversioned item and will be default selected for being part of the patch. Click Finish. This would finish creating the patch containing all the changes into the specified patch file which could be mailed to the mifos mailing list.

A subject line of [PATCH] in the mail with a brief description would be indicative of a patch being submitted.

How to apply a patch

Suppose you see a patch on the ListServ and you want to try it out on your local machine. Here's how:

1. Follow the instructions at InstallMifos so that you know how to build MIFOS from subversion and get it running
2. Apply the patch. For a short patch, it might be easiest to do this manually (if you look at the patch in a text editor, it hopefully will be more or less self-explanatory what it does - deletes lines starting with "-" and adds lines starting with "+"). For longer patches, install the "patch" program in cygwin and type "man patch" at the cygwin command line for further instructions (the short summary is something like "patch -p 5 -i patchfile.patch" where "5" is the number of pathname components that you need to skip, which you figure out by looking at the start of the patch file in a text editor).
3. (optional) running "ant run_test" may help verify that MIFOS still works (although it can take a while to run)
4. Deploy MIFOS (the same way you did from the original InstallMifos instructions in the first step).