On Contributing Patches

The commons gets a fair number of submissions from developers new to contributing patches. A lot of information to help you do this exists, but it can be hard to find. This document gathers up material about patches into one handy reference.

Before you start, please find time to browse the Apache contribution guide.

Respect The Original Style

Please respect the style of the orginal file. Make sure that your additions fit in with that style.

Every component has coding conventions and every contribution is supposed to adhere to them. You might find it a little difficult to discover the conventions used by a particular component but if you stick to the style of the original then that'll be fine.

If a patch is submitted which doesn't satisfy the component's coding conventions, then either a committer will need to rewrite the submission or it will be rejected. Getting it right in this first place will save you having to rewrite it.

Spaces Not Tabs

PLEASE NO TABS!

The source should be indented using spaces rather than tabs. The standard indentation is 4 spaces per indent - but respect the number of spaces used by the original.

Some IDEs include automatic source (re)formatting. If you use an IDE, please check that this feature is either disabled or set to use (4) spaces.

If a patch is submitted which uses tabs rather than spaces, then either a committer will have to reformat it before it's applied or the patch will be rejected. Again, it's easier to get it right in the first place rather than have to reformat and resubmit your patch.

Test Cases

Components in the commons use JUnit for unit testing. If you're not familiar with the principles of regression testing, then the JUnit site has some good articles.

Before you submit your patch, please do a clean build of the full distribution and run the unit tests (this can be done from the build script). This ensures that your patch doesn't break any existing functionality.

We strongly recommend that you create and submit test cases together with the rest of your contribution. Test cases ensure that bugs stay fixed and features don't get broken. Test cases will probably be needed anyway so submitting them saves time.

Creating A Patch

The Apache Commons source code repository holds the current source. A link to information about using the Apache Commons source code repository is available on the main Apache Commons page. Currently, Apache Commons uses the Subversion version control system.

Please create your patch against the latest revision of the files in the source code repository since this makes the job of applying the patch much easier. If you don't have a version checked out, then check one out. If you have, then please do a fresh update before you make your changes.

The patch should be in unified format. You can create a patch in this format (from Subversion) by using: 

svn diff File >> patchfile


Try to give your patch files meaningful names. This makes it easier for developers who need to apply a number of different patches.

Submitting A Patch

There are two ways to submit a patch:

  • By adding the patch as an attachment to a bug report. Apache Commons projects use the Apache JIRA Bug Tracker.
  • By mailing the patch as an attachment to the dev mailing list. The email subject should describe what the patch does and should be prefixed by [PATCH]. Make sure that it's clear which component the patch is for. Ideally the component name should be the next word after [PATCH].

But which way is better? Please use JIRA, patches sent to the mailing lists are hard to track unless they are immediately acted upon!

If it's a big patch then adding it to a bug report will save bandwidth on the mailing list (but remember to include the url in any follow-up discussions). Using a bug report also allows you to be automatically posted with status updates. Note that new bug reports (and comments on existing ones) automatically get mailed to the issues email list so there's no need to post a separate email indicating that the patch has been created.

If the patch is a fix for a bug that's already been reported then it's best to add it as an attachment to the bug report. This not only makes management easier but also it stops other developers out there wasting their time by developing independent fixes!

If there has already been discussion of the issue on the dev mailing list (but no JIRA entry has been created), then posting the patch direct to the mailing list can be simpler.

In any case, please give a detailed description of what your patch does and some reasons why it should be committed (if it's not obvious).

All the commons documentation is in the commons version control system - including this document. If you see anything that's wrong or you think that you can add something that's missing then please submit a patch!

TIA