Document Actions
Code Submission Process
Development Process
Here's a summary of the basic steps to follow when submitting a patch or doing a commit:
- Do an update from the code repository to make sure you have the latest code
- Write the tests for your code (or identify the existing tests that exercise code you will be changing)
- Write your code
- Make sure the tests that exercise your code all pass
- 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)
- 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)
- 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.
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-developer mailing list.
Running "svn diff" from the command line will generate a patch in unified diff format that can be applied using the "patch" command line program (see below) or Eclipse.
How to submit a patch
Once your patch has been created you can submit it via the mifos-developer mailing list:
- Send an email with the subject line of [PATCH] and a brief description of the patch being submitted
- Patches can generally be sent as attachments, but if the patch is more than 10KB or so, consider compressing the file with gzip or hosting it elsewhere and providing a link to the patch
- If the issue addressed by the patch exists in the issue tracker, refer to the issue number in your email. If not, create a new issue of Issue type "PATCH".
- Please also update the issue in the issue tracker:
- Attach the patch file to the issue
- Add the keyword, "Patch", once it has been attached. This keyword should be removed if a patch is not accepted.
- Within the comments, please also provide a link to the mailing list discussion where the patch has been submitted.
- When adding a patch to an issue, leave the status of the issue unchanged. When the patch has been accepted, then the status of the issue will be changed to resolved.
To monitor submitted patches please see the issue tracker patch queue.
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:
- Follow the instructions at Install Mifos so that you know how to build Mifos from subversion and get it running
- 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). Patches can also be applied within most IDEs.
- (optional) running "ant run_test" may help verify that Mifos still works (although it can take a while to run)
- Deploy Mifos (the same way you did from the original Install Mifos instructions in the first step).