Why You Should Contribute to OFBiz
By contributing your improvements back to OFBiz, you can get our entire community of developers and users to help you debug, improve, or extend the features that you need for your business. Furthermore, if your contributions improve OFBiz, then it would help to attract more users and more developers for OFBiz down the road, and eventually those users and developers would make contributions that would benefit you. Finally, the process of contributing back to the project is a great way for new users and developers to work with the existing community and learn more about OFBiz so they could tap into its power and flexibility.
How to Contribute to OFBiz
OFBiz is a community-developed open source project. What that means is that we're looking to you, the user, to help make our application better. Anybody can contribute to OFBiz--you do not have to be a committer, on an "approved" list, or be a friend or relative. All contributions are considered based on their merit for the project. You also do not need commit privileges to make a contribution. Just create a patch file and post it on our JIRA issue tracker. If you become a frequent contributor and are willing to help with the long term development of the project, you could become a project committer.
The following guidelines are meant to help contributors work with the committers and the community as a whole:
- Follow coding conventions. Make sure that your files do not have tabs where they should have spaces.
- Install the OFBIZ Subversion client configuration file
- Discuss your features with the community. What are you trying to implement, and how are you planning to do it? This is especially important if you are new to the project.
- Write clear, well-commented and understandable code. Don't take shortcuts, especially around variable names and error or warning messages. Use understandable data structures. Remember, somebody else will be working with your code down the road.
- when you prepare a patch, do your best to avoid to mix formatting changes with relevant changes (if possible, provide a separate patch containing only formatting changes): in this way the reviewers's work will be easier
- when you prepare a patch, do not insert in the code comments with author information since your name will be recorded in the commit log (that is the place were we store this kind of information)
- Internationalize your code with UI labels.
- Start out with small contributions which are easier to review. In the process, get familiar with the project's coding style and "thought process."
- Put your contributions on JIRA instead of emailing it directly to the committers, so everybody can review and comment on it. This is also required for compliance with the Apache Software Foundation's licensing requirements.
- Get other members of the community to try your patch. Write the dev list and tell them what you've done and ask them to try it out and vote for it. This would help the committers when they are reviewing your patches.
How to Send in Your Contributions
The first step is to create an account for yourself on the JIRA issue tracker and then create a new issue. Describe the contribution that you are making: are you fixing a bug, improving an existing feature, or creating a new feature? Please write as detailed a description as you can and attach screenshots if possible of what you've done. OFBIZ is a huge project, and what may be obvious to you might not be to someone else, even a committer who is familiar with the project.
Then, send in a patch file. This is a file which will describe all the differences between your modified code and the code in the OFBiz Subversion repository. You can create a patch file by using a command like this:
Code Block |
---|
$ svn diff applications/product > product.diff |
will give us a patch file for all your changes in the applications/product sub-directory and save it as product.diff.
If you have added new files, then use the "add" command first, then make the diff
Code Block |
---|
$ svn add applications/product/<my-file> $ svn diff applications/product > product.diff |
You can also specify the exact files that you'd wish to include in your patch file, in case there are files that you have modified but do not wish to submit. For example, you can use
Code Block |
---|
$ svn status applications/product |
to see which files have been modified (they start with an "M") or added (which start with a "?").
Then do:
Code Block |
---|
$ svn diff applications/product/entity/ applications/product/script/org/ofbiz/shipment/shipment/ShipmentServices.xml > product-shipment.diff |
if you only want to make a patch file of the entity/ sub-directory and the ShipmentServices.xml file.
For consistency, please make your patch files from the OFBIZ_HOME directory (usually ofbiz/) and with relative file paths. Your patch file should have file names like:
applications/party/widget/partymgr/PartyScreens.xml
framework/webtools/config/WebtoolsErrorUiLabels.properties
and should not have file names like:
C:\myfiles\ofbiz\applications\party\widget\partymgr\PartyScreens.xml
Make sure that the from/current revision of your local sandbox (checkout) is the current revision, or a very recent one, from the OFBiz SVN repository. The local revision can be checked by doing:
Code Block |
---|
$ svn info |
To make sure you have the most recent revision always do an SVN update before doing the patch with svn diff, something like this:
Code Block |
---|
$ svn up |
This must always be done before submitting a patch otherwise the patch just won't work. If your local sandbox is checked out from a separate SVN repository following the vendor branch pattern instead of directly from the OFBiz SVN, then you should do a vendor branch update, merge, and then local update in your sandbox before doing the svn diff to create the patch.
Next upload your patch file to your JIRA issue.
Finally, if there are several patch files already on an issue, please write a comment about which file should be used.