Apache Commons – On Contributing Patches

<!DOCTYPE html>  <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta name="author" content="The Apache Commons Team" /> <meta name="Date-Revision-yyyymmdd" content="20241119" /> <meta http-equiv="Content-Language" content="en" /> <title>Apache Commons – On Contributing Patches</title> <link rel="stylesheet" href="./css/bootstrap.min.css" type="text/css" /> <link rel="stylesheet" href="./css/site.css" type="text/css" /> <link rel="stylesheet" href="./css/print.css" media="print" /> <script type="text/javascript" src="./js/jquery.min.js"></script> <script type="text/javascript" src="./js/bootstrap.min.js"></script> <script type="text/javascript" src="./js/prettify.min.js"></script> <script type="text/javascript" src="./js/site.js"></script> </head> <body class="composite"> <a href="./" id="bannerLeft" title="Apache Commons logo"> <img class="logo-left" src="images/commons-logo.png" alt="Apache Commons logo"/> </a> <div class="clear"></div> <div class="navbar"> <div class="navbar-inner"> <div class="container-fluid"> <a class="brand" href="https://commons.apache.org/">Apache Commons ™</a> <ul class="nav"> <li id="publishDate">Last Published: 19 November 2024</li> <li class="divider">|</li> <li id="projectVersion">Version: unspecified</li> </ul> <div class="pull-right"> <ul class="nav"> <li> <a href="components.html" title="Components"> Components</a> </li> <li> <a href="sandbox.html" title="Sandbox"> Sandbox</a> </li> <li> <a href="dormant.html" title="Dormant"> Dormant</a> </li> <li> <a href="https://www.apachecon.com/" class="externalLink" title="ApacheCon"> ApacheCon</a> </li> <li> <a href="https://www.apache.org" class="externalLink" title="Apache"> Apache</a> </li> </ul> </div> </div> </div> </div> <div class="container-fluid"> <table class="layout-table"> <tr> <td class="sidebar"> <div class="well sidebar-nav"> <ul class="nav nav-list"> <li class="nav-header">Commons</li> <li class="none"> <a href="index.html" title="Home"> Home</a> </li> <li class="none"> <a href="https://www.apache.org/licenses/" class="externalLink" title="License"> License</a> </li> <li class="none"> <a href="mail-lists.html" title="Mailing Lists"> Mailing Lists</a> </li> <li class="none"> <a href="team.html" title="PMC"> PMC</a> </li> <li class="collapsed"> <a href="components.html" title="Components"> Components</a> </li> <li class="collapsed"> <a href="sandbox.html" title="Sandbox"> Sandbox</a> </li> <li class="collapsed"> <a href="dormant.html" title="Dormant"> Dormant</a> </li> </ul> <ul class="nav nav-list"> <li class="nav-header">Releases</li> <li class="none"> <a href="downloads/index.html" title="Releases"> Releases</a> </li> </ul> <ul class="nav nav-list"> <li class="nav-header">Source Repositories</li> <li class="none"> <a href="scminfo.html" title="General Information"> General Information</a> </li> <li class="none"> <a href="https://svn.apache.org/viewvc/commons/sandbox/" class="externalLink" title="Sandbox"> Sandbox</a> </li> <li class="none"> <a href="https://svn.apache.org/viewvc/commons/dormant/" class="externalLink" title="Dormant"> Dormant</a> </li> </ul> <ul class="nav nav-list"> <li class="nav-header">General Information</li> <li class="none"> <a href="security.html" title="Security"> Security</a> </li> <li class="none"> <a href="volunteering.html" title="Volunteering"> Volunteering</a> </li> <li class="none active"> <a href="patches.html" title="Contributing Patches"> Contributing Patches</a> </li> <li class="none"> <a href="building.html" title="Building Components"> Building Components</a> </li> <li class="none"> <a href="commons-parent" title="Commons Parent POM"> Commons Parent POM</a> </li> <li class="none"> <a href="build-plugin/index.html" title="Commons Build Plugin"> Commons Build Plugin</a> </li> <li class="none"> <a href="release-plugin/index.html" title="Commons Release Plugin"> Commons Release Plugin</a> </li> <li class="none"> <a href="site-publish.html" title="Site Publication"> Site Publication</a> </li> <li class="none"> <a href="releases/index.html" title="Releasing Components"> Releasing Components</a> </li> <li class="none"> <a href="https://cwiki.apache.org/confluence/display/COMMONS/FrontPage" class="externalLink" title="Wiki"> Wiki</a> </li> </ul> <ul class="nav nav-list"> <li class="nav-header">ASF</li> <li class="none"> <a href="https://www.apache.org/foundation/how-it-works.html" class="externalLink" title="How the ASF works"> How the ASF works</a> </li> <li class="none"> <a href="https://www.apache.org/foundation/getinvolved.html" class="externalLink" title="Get Involved"> Get Involved</a> </li> <li class="none"> <a href="https://www.apache.org/dev/" class="externalLink" title="Developer Resources"> Developer Resources</a> </li> <li class="none"> <a href="https://www.apache.org/foundation/policies/conduct.html" class="externalLink" title="Code of Conduct"> Code of Conduct</a> </li> <li class="none"> <a href="https://privacy.apache.org/policies/privacy-policy-public.html" class="externalLink" title="Privacy"> Privacy</a> </li> <li class="none"> <a href="https://www.apache.org/foundation/sponsorship.html" class="externalLink" title="Sponsorship"> Sponsorship</a> </li> <li class="none"> <a href="https://www.apache.org/foundation/thanks.html" class="externalLink" title="Thanks"> Thanks</a> </li> </ul> </div> <div id="poweredBy"> <a href="https://www.apache.org/events/current-event.html" title="ApacheCon" class="builtBy"> <img class="builtBy" alt="ApacheCon" src="https://www.apache.org/events/current-event-125x125.png" /> </a> <a href="https://maven.apache.org/" title="Maven" class="builtBy"> <img class="builtBy" alt="Maven" src="https://maven.apache.org/images/logos/maven-feather.png" /> </a> </div> </td> <td class="content"> <section> <h2><a name="On_Contributing_Patches"></a>On Contributing Patches</h2> <p> 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. </p> <p> Before you start, please find time to browse <a class="externalLink" href="http://www.apache.org/foundation/getinvolved.html">the Apache contribution guide</a>. </p> </section> <section> <h2><a name="Respect_The_Original_Style"></a>Respect The Original Style</h2> <p> Please respect the style of the orginal file. Make sure that your additions fit in with that style. </p> <p> 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. </p> <p> 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. </p> <section> <h3><a name="Spaces_Not_Tabs"></a>Spaces Not Tabs</h3> <p> <b>PLEASE NO TABS!</b> </p> <p> 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. </p> <p> 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. </p> <p>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. </p> <p> 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. </p> </section> </section> <section> <h2><a name="Test_Cases"></a>Test Cases</h2> <p> Commons Components use <a class="externalLink" href="http://www.junit.org/index.html">JUnit</a> for unit testing. If you're not familiar with the principles of unit testing, then the JUnit site has some <a class="externalLink" href="http://www.junit.org/taxonomy/term/12">good articles</a>. </p> <p> <b>Before you submit</b> 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. </p> <p> 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. </p> </section> <section> <h2><a name="Creating_A_Patch"></a>Creating A Patch</h2> <p> 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 <a class="externalLink" href="http://commons.apache.org">the main Apache Commons page</a>. Currently, Apache Commons uses the Subversion version control system. </p> <p>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. </p> <p> The patch should be in unified format. You can create a patch in this format (from Subversion) by using: </p> <div class="source"> <pre>svn diff <i>File</i> > <i>patchfile</i></pre></div> <p> 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.] </p> <p> 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. </p> <p> For example: </p> <div class="source"> <pre>svn diff <i>src/site/xdoc/patches.xml</i> > <i>COMMONSSITE-123.patch</i></pre></div><br /> </section> <section> <h2><a name="Submitting_A_Patch"></a>Submitting A Patch</h2> <p> Please use JIRA, patches sent to the mailing lists are harder to track and use up more bandwidth. </p> <p> Apache Commons projects use the main <a class="externalLink" href="https://issues.apache.org/jira/">Apache JIRA Bug Tracker</a>. Each released project has its own JIRA page, while those in the Sandbox share a single JIRA <a class="externalLink" href="https://issues.apache.org/jira/browse/SANDBOX">SANDBOX page</a>. To find a released project's JIRA page, go to its website and choose the Issue Tracking navigation link. </p> <p> 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. </p> <p> 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. </p> <p> 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 <a class="externalLink" href="https://issues.apache.org/jira/browse/COMMONSSITE">JIRA</a>! </p> <p> <b>TIA</b> </p> </section> </td> </tr> </table> </div> <div class="footer"> <p>Copyright © 2024 <a href="https://www.apache.org/">The Apache Software Foundation</a>. All Rights Reserved.</p> <?xml version="1.0" encoding="UTF-8"?> <div class="center">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.</div> </div> </body> </html>

CINXE.COM

Apache Commons – On Contributing Patches