Apache Commons – On Contributing Patches

On Contributing Patches

Apache 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.

Please try and restrict patches to the minimum necessary to implement the change. If there are a lot of irrelevant formatting or other changes, it makes it much harder to review the patch, and it may be rejected.

Test Cases

Commons Components use JUnit for unit testing. If you're not familiar with the principles of unit 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. If your patch is intended to fix a bug, it helps to create a unit test for the bug first. Test with this before and after applying the fix.

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

The patch should be created from the project root, i.e. the directory which contains the src/ folder and the main Maven pom.xml file. This ensures that the proper relative path names are included, and makes it easier to apply the patch to the correct file (there can be several files with the same name in a project). If using Eclipse to create the patch, set "Patch Root" to "Project" - not the default "Workspace". [Workspace-relative patches are not portable unless exactly the same project names are used.]

Try to give your patch files meaningful names. This makes it easier for developers who need to apply a number of different patches. Also the file should have an extension of .patch or .txt; files without extensions tend to be flagged as binary by JIRA, which makes them awkward to use.

For example:

svn diff src/site/xdoc/patches.xml > COMMONSSITE-123.patch

Submitting A Patch

Please use JIRA, patches sent to the mailing lists are harder to track and use up more bandwidth.

Apache Commons projects use the main Apache JIRA Bug Tracker. Each released project has its own JIRA page, while those in the Sandbox share a single JIRA SANDBOX page. To find a released project's JIRA page, go to its website and choose the Issue Tracking navigation link.

Please give a detailed description of what your patch does and some reasons why it should be committed (if it's not obvious). Add the patch as an attachment to a bug report, either a new one or if you find an existing report then attach it there. Both will result in an email being sent to the issues email list.

If there has already been discussion of the issue on the dev mailing list (but no JIRA entry has been created), you may wish to make a note on that discussion thread that you have created a new issue.

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 to JIRA!

TIA