CINXE.COM
How to submit a patch for project code - Apache Infrastructure Website
<!doctype html> <html class="no-js" lang="en" dir="ltr"> <head> <meta charset="utf-8"> <meta http-equiv="x-ua-compatible" content="ie=edge"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>How to submit a patch for project code - Apache Infrastructure Website</title> <link href="/css/bootstrap.min.css" rel="stylesheet"> <link href="/css/fontawesome.all.min.css" rel="stylesheet"> <link href="/css/headerlink.css" rel="stylesheet"> <script src="/highlight/highlight.min.js"></script> </head> <body class="d-flex flex-column h-100"> <main class="flex-shrink-0"> <div> <!-- nav bar --> <nav class="navbar navbar-expand-lg navbar-dark bg-dark" aria-label="Fifth navbar example"> <div class="container-fluid"> <a class="navbar-brand" href="/"><img src="/images/feather.png" style="height: 32px;"/> Apache Infrastructure</a> <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarADP" aria-controls="navbarADP" aria-expanded="false" aria-label="Toggle navigation"> <span class="navbar-toggler-icon"></span> </button> <div class="collapse navbar-collapse" id="navbarADP"> <ul class="navbar-nav me-auto mb-2 mb-lg-0"> <li class="nav-item dropdown"> <a class="nav-link dropdown-toggle" href="#" data-bs-toggle="dropdown" aria-expanded="false">About</a> <ul class="dropdown-menu"> <li><a class="dropdown-item" href="/infra-news.html">News</a></li> <li><a class="dropdown-item" href="/blog/">The Infrastructure Blog</a></li> <li><a class="dropdown-item" href="/roundtable.html">The Infrastructure Roundtable</a></li> <li><a class="dropdown-item" href="/team.html">About the team</a></li> </ul> </li> <li class="nav-item"> <a class="nav-link" href="/policies.html">Policies</a> </li> <li class="nav-item dropdown"> <a class="nav-link dropdown-toggle" href="#" data-bs-toggle="dropdown" aria-expanded="false">Services and Tools</a> <ul class="dropdown-menu"> <li><a class="dropdown-item" href="/services.html">Services and Tools</a></li> <li><a class="dropdown-item" href="https://blocky.apache.org/">Blocky</a></li> <li><a class="dropdown-item" href="https://app.datadoghq.com/account/login?next=%2Finfrastructure">DataDog</a></li> <li><a class="dropdown-item" href="https://whimsy.apache.org/roster/committer/" target="_blank">Committer Search</a></li> </ul> </li> <li class="nav-item dropdown"> <a class="nav-link dropdown-toggle" href="#" data-bs-toggle="dropdown" aria-expanded="false">Documentation</a> <ul class="dropdown-menu"> <li><a class="dropdown-item" href="/doc.html">Contribute</a></li> <li><a class="dropdown-item" href="/infra-volunteer.html">Volunteer with Infra</a></li> <li><a class="dropdown-item" href="/how-to-mirror.html">Become an ASF download mirror</a></li> <li><a class="dropdown-item" href="/hosting-external-agent.html">Host a Jenkins or Buildbot agent</a></li> </ul> </li> <li class="nav-item"> <a class="nav-link" href="/stats.html">Status</a> </li> <li class="nav-item"> <a class="nav-link" href="/contact.html">Contact Us</a> </li> </ul> </div> </div> </nav> <!-- page contents --> <div id="contents"> <div class="bg-white p-5 rounded"> <div class="col-sm-8 mx-auto"> <h1> How to submit a patch for project code </h1> <p>To contribute a change or addition to existing source code:</p> <h3>Using Subversion</h3> <p>See <a href="svn-basics.html">Subversion basics</a></p> <ol> <li>Check out the latest copy of the source code from the project's code repository.</li> <li>Change the source files to incorporate your change or addition. Make sure you provide appropriate source code documentation (like javadoc for Java sources), and follow the project's coding conventions.</li> <li>Check the software still compiles and runs correctly on your local machine.</li> <li>Run any unit or regression tests the software may have.</li> </ol> <p>If all this works, you can create your patch. Remove all build products and remnants (like any 'build', 'dist' or 'bin' directories) from the module tree, then build the actual patch. Here's how to do it using the command line SVN client under unix:</p> <p>Apache projects prefer the unified diff format. The subversion tool creates that automatically. If you use other tools, please refer to their documentation for details on setting the diff format.</p> <pre><code> # location where the modules are stored cd checkout</p> <div class="codehilite"><pre><span class="c"># directory of the module</span> <span class="n">cd</span> <span class="n">site</span> <span class="c"># creation of the diff</span> <span class="n">svn</span> <span class="nb">diff</span> <span class="o">&gt;</span> <span class="n">site</span><span class="p">.</span><span class="nb">patch</span> </pre></div> </code></pre> <p>The Subversion client now examines all subdirectories for changed files, then compares the changed file to the one on the server. It generates the patch.</p> <p>The '>' redirection results in the resulting patch being put in a text file named (in this case) <code>site.patch</code>.</p> <p>With your patch generated, you need to send it to the developers. Different projects have different preferences for this. Usually you add it as an attachment to the relevant bug report in the bug tracking database. If a relevant bug report doesn't exist yet, create one.</p> <h3>Using Git</h3> <p>See <a href="git-primer.html">Getting started with Git</a> for general information.</p> <p>The general pattern for creating and submitting a patch for a project using Git is:</p> <ol start="0"> <li>Before you start: talk to the project team! Somebody else may be working on the same thing, or there may be some not-obvious reason why what you are proposing would take the project in a different direction from its current path. Usually, you will get a "Great! Go ahead," response; and if you find out your proposed change is not needed for some reason, you will have saved some time for some other initiative.</li> <li>Create and download a branch of the project.</li> <li>In that branch, on your local computer, change the source files to incorporate your change or addition. Make sure you provide appropriate source code documentation and follow the project's coding conventions.</li> <li>Check the software still compiles and runs correctly on your local machine.</li> <li>Run any unit or regression tests the software may have.</li> <li>Upload your changes from your local computer to the branch you created.</li> <li>Create a pull request to merge your branch into the trunk of the project's code.</li> </ol> <p>One or more of the project's committers will review your proposed changes and, if all is well, merge them.</p> <h3>In general</h3> <p>A very few projects don't use an issue tracker. In that case, send the patch as an attachment to an e-mail with a subject prefixed with "<code>[PATCH]</code>", to the appropriate development mailing list. If the patch is large, please ask before e-mailing it in case there is a better way to provide it.</p> <p>Supply a different patch per issue. A patch can span multiple files but you should normally try not to fix multiple bugs in a single patch, unless those bugs are intimately related.</p> <p>Be patient if your patch is not applied as fast as you'd like (open source developers are all volunteers, often doing the development in their spare time) or a developer asks you to make changes to the patch. If you do not receive any feedback in a reasonable amount of time (say, a week or two), feel free to send a follow-up e-mail to the developer list.</p> </div> </div> </div> <!-- footer --> <div class="row"> <div class="large-12 medium-12 columns"> <p style="font-style: italic; font-size: 0.8rem; text-align: center;"> Copyright 2024, <a href="https://www.apache.org/">The Apache Software Foundation</a>, Licensed under the <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.<br/> Apache® and the Apache feather logo are trademarks of The Apache Software Foundation. </p> </div> </div> <script type="application/ecmascript" src="/js/bootstrap.bundle.min.js" integrity="sha384-OERcA2EqjJCMA+/3y+gxIOqMEjwtxJY7qPCqsdltbNJuaOe923+mo//f6V8Qbsw3"></script> </div> </main> <script>hljs.initHighlightingOnLoad();</script> </body> </html>