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.

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!

Apache Commons, Apache, the Apache feather logo, and the Apache Commons project logos are trademarks of The Apache Software Foundation.
All other marks mentioned may be trademarks or registered trademarks of their respective owners.