Access to add and change pages is restricted. See: https://cwiki.apache.org/confluence/display/OFBIZ/Wiki+access

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 33 Next »

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.

  • Create an account there if you do not have one
  • Login
  • Search if an issue for what you are after already exists by using the "Find issues"
  • If an issue on the subject already exists you can add a comment on it
  • If a issue does not exist, create a new one selecting the "create new issue" command
  • Select the OFBiz project and the issue type
  • Fill in all fields, give as many detail you think necessary
  • If you need to attach files or screenshots you must edit the issue after the creation

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:

  1. Follow coding conventions. Seriously, read that document.
  2. Install the OFBIZ Subversion client configuration file
  3. Follow the 2 main rules for committers:
    1. Rule #1 for a committer is the same as for a doctor: first do no harm. Nothing should be committed that breaks existing functionality without replacing it either before or in the same commit. Whatever you are working with someone developed it and chances are someone is using it, and possibly MANY people.
    2. Rule #2 for a committer is the same as for a scientist: read before you write. When you're getting started a good time ratio for read to write is around 20 to 1. Once you're a total OFBiz pro who knows as much as any living person about the project, you can probably reduce that to about 3 to 1.
  4. 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.
  5. 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.
  6. 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 reviewer's work will be easier
  7. 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)
  8. Internationalize your code with UI labels.
  9. Start out with small contributions which are easier to review. In the process, get familiar with the project's coding style and "thought process."
  10. Keep patches and contributions easy to review and commit. Even if a lot of code is touched, try to keep things isolated and the intent of the patch(es) clear. Remember that most committers can find 20 minutes here and there, but it is very hard to fit in the 2-4 hour time block required to review and commit a larger patch (especially if it touches ANY lower level or more sensitive or complex artifacts, and this requires more thorough review).
  11. Put your contributions on JIRA instead of emailing it directly to the committers, so everybody can review and comment on it. Though it is not necessary this makes contributions more traceable for the licensing through the Apache Software Foundation.
  12. 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 will help the committers when they are reviewing your patches as there will be more confidence that the patch does what it is intended to do, and doesn't break anything else.

If you are planning a larger contribution, please follow the following tips to facilitate both licensing and collaboration. These tips will make it easier for committers to review and incorporate your work, and will overall speed up your development process as you'll be asking the OFBiz team to do a number of small, simple tasks rather than a couple of large tasks that a committer will have to find significant time to review and commit.

  1. Do not implement large blocks of artifacts (code, etc) on your own and then contribute them to OFBiz.
  2. If you have a large block of code to contribute we can work with you on that, but it requires a different review and legal vetting process than normal contributions, as described on http://incubator.apache.org/ip-clearance/index.html.
  3. When a method is deprecated, it should be explained which method should be used, and what has changed.
  4. Instead develop and contribute as you go. This means develop as you would normally, but interact with the OFBiz community through mailing lists and contribute patches regularly. # If you are do not have a committer on your team this can slow down development, so do what you can to "sell" one of the committers on your project and get an ally on the committing team to regularly review and commit your patches. Note that if you let us know in advance that you are planning a larger effort of this nature, we can perhaps find a volunteer beforehand to work with you on this.
  5. Just please remember that there is no paid staff on OFBiz, all are volunteers. You may see your patch sit in Jira for a long time while committers work on other things. This usually happens because a committer is working on a priority for the project that has been a problem for a while, or on a paid contract in order to survive and to be able to continue helping with OFBiz.
  6. It might be tempting to run your effort without getting an OFBiz committer involved, but keep in mind that committers can help you with technical, business, and legal concerns either on their own or through collaboration with others in the project on in the ASF more generally.

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:

$ 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

$ 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

$ svn status applications/product

to see which files have been modified (they start with an "M") or added (which start with a "?").

Then do:

$ 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:

$ 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:

$ 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. Please use .patch as extension, some tools use extensions and this facilitates commiters works.
Finally, if there are several patch files already on an issue, please write a comment about which file should be used. A best practice is also to keep the same filename if a patch file is updated. Jira will take care of that and will keep (better for history) but gray deprecated files with the same filename. It's easier for commiter to see at 1st glance which file to use. You can read in 1st comment below what may happen when not using the same filename.

When a Jira issue is totaly resolved, we prefer to close the issue than to put it as resolved. There are some cases where there is a tentative resolution and you don't want to close the case because you want the reporter or someone to review and test the fix to make sure it was what was intended. If it is a simpler issue and especially if you are the reporter, then it is best to just close it right away rather than coming back to it later to close.

Why is it Taking So Long to Get My Patch into OFBiz?

The first thing to remember is that in order for something to get done an individual or group must have sufficient ability and time to do it. There are no paid OFBiz committers, everyone works on a volunteer basis. This is a natural side effect of OFBiz being a community-driven project rather than "commercial open source".

When someone submits a patch they are asking for someone in the group of committers to do something for free. Sometimes because of the volume of patches it is overlooked and then with a constant stream of new issues, complaints, questions, etc it may be a long time (if ever) before someone gets back to it. Most unfortunately there aren't any committers that can work on contributing to OFBiz full-time because so far there are no committers that don't need to also earn a living. Most committers work with OFBiz in their day job, and because of the size and complexity of the project so far that seems to be the only way someone even can consistently contribute to OFBiz. That doesn't mean they are paid to work on your issue though, unless you and they get lucky and it happens to be related to a paid client objective.

If you REALLY want your patch in, you can get it in. If you want it in, your job is to help the committers get it in. You can recruit others on the mailing lists to review and test your patch. This is really important, because OFBiz is fairly complex and many patches break rule #1, which is in short, "first do no harm". In other words, do break stuff that already exists that other people implemented, and that other people are using.

There is also another option... as mentioned above OFBiz is unfunded and every committer has an employer of some sort, often a handful of clients. This would explain why things are getting committed all the time, even though sometimes the volume of patches getting reviewed and committed is pretty low. If committers are lucky then they get to work on stuff that goes back into OFBiz, and that is ONLY reason that most of the functionality in OFBiz exists at all, especially in the applications (most of the framework, on the other hand, was not ever sponsored). Some people see this as unfair. Others see it as a great stroke of luck that they can take advantage of.

If this isn't working for you, then consider getting more involved with OFBiz or somehow making it possible for others to get more involved with OFBiz. There are many ways you can help, even without becoming a committer yourself. There are the exact same things you can do in order to become a committer if you do enough of them, but of course you can do all of these without any longer term commitment or hoops to jump through. You don't even have to get a committer or PMC member to do anything in order to do these things!

  1. Subscribe to the dev mailing list, try to read the majority of the messages, and participate in discussions there
  2. Review and comment on issues in the Jira issue tracker
  3. Apply patches from Jira locally and test them and comment on the results
  4. Create patches to fix issues reported in Jira
  5. Get to know OFBiz and submit patches to fix problems or annoyances you find
  6. Follow all of the rest of the advice in this document

How Do I Become a Committer Myself?

If you're interested in becoming a committer, that's great! We would love to have you and the whole community will really appreciate your help.

Being a committer can be a great help to your employer and/or clients. It can also be a great asset in your personal and career growth. There is a guarantee that in the course of your activities you will learn and grow. You'll learn about building enterprise applications, both the technical and business sides of them. You'll also learn a lot about working with other people, especially working with other people remotely.

For more information and to get started see the Committers Roles and Responsibilities page.

  • No labels