CINXE.COM

<!DOCTYPE html> <html> <head> <meta charset="UTF-8"> <meta http-equiv="x-ua-compatible" content="ie=edge"> <title>Apache Subversion - Community Guide - General Overview</title> <meta http-equiv="Content-Type" content="text/html;charset=utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <link rel="manifest" href="/site.webmanifest"> <link rel="apple-touch-icon" href="/icon.png"> <link rel="icon" type="image/png" href="/icon.png"> <link rel="stylesheet" href="/style/site.css" type="text/css" media="all"> <meta name="theme-color" content="#98b0d4"> </head> <body> <div id="site-banner"> <div style="font-style: italic; text-align: center;" id="site-banner-apachelogo"> <a href="https://www.apache.org/" ><img src="/images/asf_logo_wide.svg" alt="Apache Software Foundation" /></a> </div> <a href="/"> <img src="/images/svn-name-banner.svg" width="379" height="80" alt="[S] Subversion" id="site-banner-svnlogo" /></a> </div>  <div id="site-nav"> <label for="hamburger">☰</label> <input type="checkbox" id="hamburger"/> <nav id="site-nav-menu"> <p>About Subversion <ul> <li><a href="/news.html">News</a></li> <li><a href="/features.html">Features</a></li> <li><a href="/docs/">Documentation</a></li> <li><a href="/faq.html">FAQ</a></li> <li><a href="/roadmap.html">Roadmap</a></li> <li><a href="/security/">Security</a></li> <li><a href="/quick-start">Quick Start</a></li> <li><a href="/blog/">Blog</a></li> </ul> </p> <p>Getting Subversion <ul> <li><a href="/packages.html">Binary Packages</a></li> <li><a href="/download.cgi">Source Download</a></li> <li><a href="/docs/release-notes/">Release Notes</a></li> </ul> </p> <p>Community <ul> <li><a href="/mailing-lists.html">Mailing Lists</a></li> <li><a href="/reporting-issues.html">Reporting Issues</a></li> <li><a href="https://cwiki.apache.org/confluence/display/SVN/">Wiki</a></li> <li><a href="/contributing.html">Getting Involved</a></li> <li><a href="/source-code.html">Source Code</a></li> </ul> </p> <p>About the <acronym title="Apache Software Foundation">ASF</acronym> <ul> <li><a class="linkaway" href="https://www.apache.org/licenses/">License</a></li> <li><a class="linkaway" href="https://www.apache.org/foundation/sponsorship.html">Donate</a></li> <li><a class="linkaway" href="https://www.apache.org/foundation/thanks.html">Thanks</a></li> </ul> </p> <p id="site-search"> <form action="https://www.google.com/search" method="get" style="margin-top: 10px; margin-bottom: 10px; display: inline;"> <div style="display: inline;"> <input value="subversion.apache.org" name="sitesearch" type="hidden" /> <input name="q" id="query" type="text" placeholder="Search..." style="width: 10em" /> <input name="Search" value="Go" type="submit"/> </div> </form> </p>  <p id="site-apachecon-block"> <p><a href="https://www.apache.org/events/current-event.html" ><img src="https://www.apache.org/events/current-event-125x125.png" alt="ApacheCon" /></a></p> </p>  <p id="site-svnbook-block"> <p>Read the official Subversion documentation <a href="https://svnbook.red-bean.com/" class="linkaway nopadding">online</a>!</p> <p><a href="https://svnbook.red-bean.com/" ><img src="/images/svnbook-cover.jpg" alt="Version Control With Subversion"/></a></p> </p>  <p id="copyright"> <p>Copyright © 2023 <a href="https://www.apache.org/" class="nopadding">The Apache Software Foundation</a>, Licensed under the <a href="https://www.apache.org/licenses/LICENSE-2.0" class="nopadding">Apache License, Version 2.0</a>. Apache, Apache Subversion, and the Apache feather logo are trademarks of The Apache Software Foundation. Subversion and the Apache Subversion logo are registered trademarks of The Apache Software Foundation.</p> <p><a href="https://privacy.apache.org/policies/privacy-policy-public.html" class="nopadding">Privacy policy</a></p> </p>  </nav> </div>  <div id="site-content"> <div id="site-notice">  </div>  <p style="text-align: right; font-style: italic;">[You can also view the <a href="community-guide.html">single-page version</a> of this document.]</p> <ul class="topmenu"> <li><a href="/docs/community-guide/general.html">General Overview</a></li> <li><a href="/docs/community-guide/roles.html">Community Roles</a></li> <li><a href="/docs/community-guide/conventions.html">Coding and Commit Conventions</a></li> <li><a href="/docs/community-guide/building.html">Building and Testing</a></li> <li><a href="/docs/community-guide/debugging.html">Debugging Subversion</a></li> <li><a href="/docs/community-guide/web.html">Web Site Changes</a></li> <li><a href="/docs/community-guide/mailing-lists.html">Mailing Lists</a></li> <li><a href="/docs/community-guide/issues.html">Bugs/Issues</a></li> <li><a href="/docs/community-guide/releasing.html">Making Subversion Releases</a></li> <li><a href="/docs/community-guide/l10n.html">Localization</a></li> </ul> <div class="h1" id="general"> <h1>General Overview <a class="sectionlink" href="general.html#general" title="Link to this section">¶</a> </h1> <ul> <li><a href="general.html#participating">Participating in the community</a></li> <li><a href="general.html#docs">Theory and documentation</a></li> <li><a href="general.html#code-to-read">Code to read</a></li> <li><a href="general.html#directory-layout">Directory layout</a></li> <li><a href="general.html#branch-policy">Branch policy</a></li> <li><a href="general.html#documenting">Documentation</a></li> <li><a href="general.html#patches">Patch submission guidelines</a></li> </ul> <div class="h2" id="participating"> <h2>Participating in the community <a class="sectionlink" href="general.html#participating" title="Link to this section">¶</a> </h2> <p>Although Subversion was originally sponsored and hosted by CollabNet (<a rel="nofollow" href="https://www.collab.net/">https://www.collab.net/</a>), it's a true open-source project under the Apache License, Version 2.0. A number of Subversion's developers are paid by their employers to improve Subversion, while many others are simply excellent volunteers who are interested in building a better version control system.</p> <p>The community exists mainly through mailing lists and a Subversion repository. To participate:</p> <li><p>Join the "dev", "commits", and "announce" mailing lists. The dev list, dev@subversion.apache.org, is where almost all discussion takes place. All development questions should go there, though you might want to check the list archives first. The "commits" list receives automated commit emails. See <a href="/mailing-lists.html" >https://subversion.apache.org/mailing-lists.html</a> for details.</p></li> <li><p>Get a copy of the latest development sources from <a href="https://svn.apache.org/repos/asf/subversion/trunk/" >https://svn.apache.org/repos/asf/subversion/trunk/</a> <br /> New development always takes place on trunk. Bugfixes, enhancements, and new features are backported from there to the various release branches.</p></li> </ul> <p>For several years, the Subversion Community meet in Berlin for a Hackathon once a year: <a rel="nofollow" href="https://web.archive.org/web/20170227085903/https://www.elegosoft.com/en_US/page/apache-subversion-hackathon-berlin-2016" >2016</a>, <a rel="nofollow" href="https://web.archive.org/web/20171206000855/https://www.elegosoft.com/en_US/page/apache-subversion-hackathon-berlin-2015" >2015</a>, <a rel="nofollow" href="https://web.archive.org/web/20171205232732/https://www.elegosoft.com/en_US/page/nachlese-apache-subversion-2014-berlin-hackathon" >2014</a>, <a rel="nofollow" href="https://web.archive.org/web/20171206002300/https://www.elegosoft.com/en_US/page/nachlese-subversion-hackathon-berlin-2013" >2013</a>, <a rel="nofollow" href="https://web.archive.org/web/20171205232529/https://www.elegosoft.com/en_US/page/nachlese-svn-day-berlin-2012" >2012</a>, <a rel="nofollow" href="https://web.archive.org/web/20171205204626/https://www.elegosoft.com/en_US/page/nachlese-svn-day-berlin-2011" >2011</a> and <a rel="nofollow" href="https://web.archive.org/web/20171206002600/https://www.elegosoft.com/en_US/page/nachlese-subversion-day-berlin-2010" >2010</a> [linked from archive.org, some media links do not work].</p> <p>There are many ways to join the project, either by writing code, or by testing and/or helping to manage the bug database. If you'd like to contribute, then look at:</p> <ul> <li><p>The bugs/issues database <a href="https://issues.apache.org/jira/projects/SVN/issues" >https://issues.apache.org/jira/projects/SVN/issues</a></p></li> </ul> <p>To submit code, simply send your patches to dev@subversion.apache.org. No, wait, first read the rest of this file, <i>then</i> start sending patches to dev@subversion.apache.org. :-)</p> <p>To help manage the issues database, read over the issue summaries, looking and testing for issues that are either invalid, or are duplicates of other issues. Both kinds are very common, the first because bugs often get unknowingly fixed as side effects of other changes in the code, and the second because people sometimes file an issue without noticing that it has already been reported. If you are not sure about an issue, post a question to dev@subversion.apache.org. ("Subversion: We're here to help you help us!")</p> <p>Another way to help is to set up automated builds and test suite runs of Subversion on some platform, and have the output sent to the notifications@subversion.apache.org mailing list. See more details at <a href="/mailing-lists.html#notifications-ml" >the mailing lists page</a>.</p> <p>Finally, despite the online nature of the Subversion project and the human contact abstraction that results from that fact, it is important to realize that there are <em>real</em> people at the end of all contributions. Treat all other community members as you would expect to be treated. Review the contribution, not the contributor; don't annoy others, and don't become easily annoyed yourself.</p> </div>  <div class="h2" id="docs"> <h2>Theory and documentation <a class="sectionlink" href="general.html#docs" title="Link to this section">¶</a> </h2> <ol> <li><p>Design</p> <p>A <a href="https://svn.apache.org/repos/asf/subversion/trunk/notes/subversion-design.html" >design spec</a> was written in June 2000, and is a bit out of date. But it still gives a good theoretical introduction to the inner workings of the repository, and to Subversion's various layers.</p> </li> <li><p>API Documentation</p> <p>See the section on the <a href="general.html#doxygen-docs">public API documentation</a> for more information.</p> </li> <li><p>Delta Editors</p> <p>Karl Fogel wrote a chapter for O'Reilly's 2007 book <a rel="nofollow" href="https://www.oreilly.com/library/view/beautiful-code/9780596510046/"> Beautiful Code: Leading Programmers Explain How They Think</a> covering the design and use of <a href="https://www.red-bean.com/kfogel/beautiful-code/bc-chapter-02.html"> Subversion's delta editor interface</a>.</p> </li> <li> <p>Network Protocols</p> <p>The <a href="https://svn.apache.org/repos/asf/subversion/trunk/notes/http-and-webdav/webdav-usage.html" >WebDAV Usage</a> document is an introduction to Subversion's DAV network protocol, which is an extended dialect of HTTP and uses URLs beginning with "http://" or "https://".</p> <p>The <a href="https://svn.apache.org/repos/asf/subversion/trunk/subversion/libsvn_ra_svn/protocol" >SVN Protocol</a> document contains a formal description of Subversion ra_svn network protocol, which is a custom protocol on port 3690 (by default), whose URLs begin with "svn://" or "svn+ssh://".</p> </li> <li><p>User Manual</p> <p>Version Control with Subversion is a book published by O'Reilly that shows in detail how to effectively use Subversion. The text of the book is free, and is actively being revised. On-line versions are available at <a href="https://svnbook.red-bean.com/" >https://svnbook.red-bean.com/</a>. The XML source and translations to other languages are maintained in their own repository at <a href="https://sourceforge.net/projects/svnbook/" >https://sourceforge.net/projects/svnbook/</a>.</p> </li> <li><p>System notes</p> <p>A lot of the design ideas for particular aspects of the system have been documented in individual files in the <a href="https://svn.apache.org/repos/asf/subversion/trunk/notes/" >notes/</a> directory.</p> </li> </ol> </div>  <div class="h2" id="code-to-read"> <h2>Code to read <a class="sectionlink" href="general.html#code-to-read" title="Link to this section">¶</a> </h2> <p>Before you can contribute code, you'll need to familiarize yourself with the existing code base and interfaces.</p> <p>Check out a copy of Subversion (anonymously, if you don't yet have an account with commit access) — so you can look at the code.</p> <p>Within 'subversion/include/' are a bunch of header files with huge doc comments. If you read through these, you'll have a pretty good understanding of the implementation details. Here's a suggested perusal order:</p> <ol> <li><p>the basic building blocks: <a href= "/docs/api/latest/svn__string_8h.html"> svn_string.h</a>, <a href= "/docs/api/latest/svn__error_8h.html"> svn_error.h</a>, <a href= "/docs/api/latest/svn__types_8h.html"> svn_types.h</a></p> </li> <li><p> <a href= "/docs/api/latest/svn__io_8h.html"> svn_io.h</a>, <a href= "/docs/api/latest/svn__path_8h.html"> svn_path.h</a>, <a href= "/docs/api/latest/svn__hash_8h.html"> svn_hash.h</a>, <a href= "/docs/api/latest/svn__xml_8h.html"> svn_xml.h</a></p> </li> <li><p>the critical interface: <a href= "/docs/api/latest/svn__delta_8h.html"> svn_delta.h</a></p> </li> <li><p>client-side interfaces: <a href= "/docs/api/latest/svn__ra_8h.html"> svn_ra.h</a>, <a href= "/docs/api/latest/svn__wc_8h.html"> svn_wc.h</a>, <a href= "/docs/api/latest/svn__client_8h.html"> svn_client.h</a></p> </li> <li><p>the repository and versioned filesystem: <a href= "/docs/api/latest/svn__repos_8h.html"> svn_repos.h</a>, <a href= "/docs/api/latest/svn__fs_8h.html"> svn_fs.h</a></p> </li> </ol> <p>Subversion tries to stay portable by using only the <a href="https://en.wikipedia.org/wiki/ANSI_C#C89_and_C90">C89/C90</a> dialect of <a href="https://en.wikipedia.org/wiki/ANSI_C">ANSI/ISO C</a> and by using the Apache Portable Runtime (APR) library. APR is the portability layer used by the Apache httpd server, and more information can be found at <a href="https://apr.apache.org/" >https://apr.apache.org/</a>.</p> <p>Because Subversion depends so heavily on APR, it may be hard to understand Subversion without first glancing over certain header files in APR (look in 'apr/include/'):</p> <ul> <li><p>memory pools: <a href= "/docs/apr/1.4/apr__pools_8h.html"> apr_pools.h</a></p></li> <li><p>filesystem access: <a href= "/docs/apr/1.4/apr__file__io_8h.html"> apr_file_io.h</a></p></li> <li><p>hashes and arrays: <a href= "/docs/apr/1.4/apr__hash_8h.html"> apr_hash.h</a>, <a href= "/docs/apr/1.4/apr__tables_8h.html"> apr_tables.h</a> </p></li> </ul> <p>Subversion also tries to deliver reliable and secure software. This can only be achieved by developers who understand secure programming in the C programming language. Please see 'notes/assurance.txt' for the full rationale behind this. Specifically, you should make it a point to carefully read David Wheeler's Secure Programming (as mentioned in <a href="https://svn.apache.org/repos/asf/subversion/trunk/notes/assurance.txt"> 'notes/assurance.txt'</a>). If at any point you have questions about the security implications of a change, you are urged to ask for review on the developer mailing list.</p> </div>  <div class="h2" id="directory-layout"> <h2>Directory layout <a class="sectionlink" href="general.html#directory-layout" title="Link to this section">¶</a> </h2> <p>A rough guide to the source tree:</p> <ul> <li><p><tt><a href="https://svn.apache.org/repos/asf/subversion/trunk/doc/"> doc/</a></tt><br /> User and Developer documentation.</p> </li> <li><p><tt><a href="https://svn.apache.org/repos/asf/subversion/trunk/tools/"> tools/</a></tt><br /> Stuff that works with Subversion, but that Subversion doesn't depend on. Code in tools/ is maintained collectively by the Subversion project, and is under the same open source copyright as Subversion itself.</p> </li> <li><p><tt><a href="https://svn.apache.org/repos/asf/subversion/trunk/contrib/"> contrib/</a></tt><br /> Stuff that works with Subversion, but that Subversion doesn't depend on, and that is maintained by individuals who may or may not participate in Subversion development. Code in contrib/ is open source, but may have a different license or copyright holder than Subversion itself.</p> </li> <li><p><tt><a href="https://svn.apache.org/repos/asf/subversion/trunk/subversion/"> subversion/</a></tt><br /> Source code to Subversion itself (as opposed to external libraries).</p> </li> <li><p><tt><a href="https://svn.apache.org/repos/asf/subversion/trunk/subversion/include/"> subversion/include/</a></tt><br /> Public header files for users of Subversion libraries.</p> </li> <li><p><tt><a href="https://svn.apache.org/repos/asf/subversion/trunk/subversion/include/private/"> subversion/include/private/</a></tt><br /> Private header files shared internally by Subversion libraries.</p> </li> <li><p><tt><a href="https://svn.apache.org/repos/asf/subversion/trunk/subversion/libsvn_fs/"> subversion/libsvn_fs/</a></tt><br /> The versioning "filesystem" API.</p> </li> <li><p><tt><a href="https://svn.apache.org/repos/asf/subversion/trunk/subversion/libsvn_repos/"> subversion/libsvn_repos/</a></tt><br /> Repository functionality built around the `libsvn_fs' core.</p> </li> <li><p><tt><a href="https://svn.apache.org/repos/asf/subversion/trunk/subversion/libsvn_delta/"> subversion/libsvn_delta/</a></tt><br /> Common code for tree deltas, text deltas, and property deltas.</p> </li> <li><p><tt><a href="https://svn.apache.org/repos/asf/subversion/trunk/subversion/libsvn_wc/"> subversion/libsvn_wc/</a></tt><br /> Common code for working copies.</p> </li> <li><p><tt><a href="https://svn.apache.org/repos/asf/subversion/trunk/subversion/libsvn_ra/"> subversion/libsvn_ra/</a></tt><br /> Common code for repository access.</p> </li> <li><p><tt><a href="https://svn.apache.org/repos/asf/subversion/trunk/subversion/libsvn_client/"> subversion/libsvn_client/</a></tt><br /> Common code for client operations.</p> </li> <li><p><tt><a href="https://svn.apache.org/repos/asf/subversion/trunk/subversion/svn/"> subversion/svn/</a></tt><br /> The command line client.</p> </li> <li><p><tt><a href="https://svn.apache.org/repos/asf/subversion/trunk/subversion/tests/"> subversion/tests/</a></tt><br /> Automated test suite.</p> </li> </ul> </div>  <div class="h2" id="branch-policy"> <h2>Branching policy <a class="sectionlink" href="general.html#branch-policy" title="Link to this section">¶</a> </h2> <p>The Subversion project strongly prefers that active development happens in the common trunk. Changes made to trunk have the highest visibility and get the greatest amount of exercise that can be expected from unreleased code. For this to be beneficial to everyone, though, our trunk is expected at all times to be stable. It should build. It should work. It might not be release-ready, but it should certainly be test-suite ready.</p> <p>We also strongly prefer to see large changes broken up into several, smaller, logical commits — each of which is expected to meet the aforementioned requirements of stability.</p> <p>That said, we understand that it can be nearly impossible to apply all these policies to particularly large changes (new features, sweeping code reorganizations, etc.). It is in those situations that you might consider using a custom branch dedicated to your development task. The following are some guidelines to make your branch-based development work go smoothly.</p> <div class="h3" id="branch-creation-and-management"> <h3>Branch creation and management <a class="sectionlink" href="general.html#branch-creation-and-management" title="Link to this section">¶</a> </h3> <p>There's nothing particularly complex about branch-based development. You make a branch from the trunk (or from whatever branch best serves as both source and destination for your work), and you do your work on it. Subversion's merge tracking feature has greatly helped to reduce the sort of mental overhead required to work in this way, so making good use of that feature (by using Subversion 1.5 or newer clients, and by performing all merges to and from the roots of branches) is highly encouraged.</p> <p>For our policy on log messages for your branch, please note the section on <a href="conventions.html#log-messages"> writing log messages.</a></p> </div>  <div class="h3" id="lightweight-branches"> <h3>Lightweight branches <a class="sectionlink" href="general.html#lightweight-branches" title="Link to this section">¶</a> </h3> <p>If you're working on a feature or bugfix in stages involving multiple commits, and some of the intermediate stages aren't stable enough to go on trunk, then create a temporary branch in /branches. There's no need to ask — just do it. It's fine to try out experimental ideas in a temporary branch, too. And all the preceding applies to partial as well as full committers. It even applies to committers of other <a href="https://www.apache.org/">ASF</a> projects, but please talk to us (on dev@)—introduce yourself and the problem you plan to work on.</p> <p>When you're done with the branch — when you've either merged it to trunk or given up on it — please remember to remove it.</p> <p>See also the <a href="roles.html#partial-commit-access" >section on partial commit access</a> for our policy on offering commit access to experimental branches.</p> </div>  <div class="h3" id="branch-readme-files"> <h3>BRANCH-README files <a class="sectionlink" href="general.html#branch-readme-files" title="Link to this section">¶</a> </h3> <p>For branches you expect to be longer-lived, we recommend the creation and regular updating of a file in the root of your branch named <tt>BRANCH-README</tt>. Such a file provides you with a great, central place to describe the following aspects of your branch:</p> <ul> <li><p>The basic purpose of your branch: what bug it exists to fix, or feature to implement; what issue number(s) it relates to; what list discussion threads surround it; what design docs exists to describe the situation.</p></li> <li><p>What style of branch management you are using: is this a feature branch that will regularly be kept in sync with its parent branch and ultimately reintegrated back to that parent branch? Is it a fork that is not expected to be merged back to its parent branch in the foreseeable future? Does it relate to any other branches?</p></li> <li><p>What tasks remain for you to accomplish on your branch? Are those tasks claimed by someone? Do they need more design input? How can others help you?</p></li> </ul> <p>Here is an example BRANCH-README file that demonstrates what we're talking about:</p> <pre style="margin-left: 0.25in;"> This branch exists for the resolution of issue #8810, per the ideas documented in /trunk/notes/frobnobbing-feature.txt. It is a feature branch, receiving regular sync merges from /trunk, and expected to be reintegrated back thereto. TODO: * compose regression tests [DONE] * add frob identification logic [STARTED (fitz)] * add nobbing bits [] </pre> <p>Why all the fuss? Because this project idealizes communication and collaboration, understanding that the latter is more likely to happen when the former is a point of emphasis.</p> <p>Just remember when you merge your branch back to its source to delete the <tt>BRANCH-README</tt> file.</p> </div>  </div>  <div class="h2" id="documenting"> <h2>Documentation <a class="sectionlink" href="general.html#documenting" title="Link to this section">¶</a> </h2> <div class="h3" id="document-everything"> <h3>Document Everything <a class="sectionlink" href="general.html#document-everything" title="Link to this section">¶</a> </h3> <p>Every function, whether public or internal, must start out with a documentation comment that describes what the function does. The documentation should mention every parameter received by the function, every possible return value, and (if not obvious) the conditions under which the function could return an error.</p> <p>For internal documentation put the parameter names in upper case in the doc string, even when they are not upper case in the actual declaration, so that they stand out to human readers.</p> <p>For public or semi-public API functions, the doc string should go above the function in the .h file where it is declared; otherwise, it goes above the function definition in the .c file.</p> <p>For structure types, document each individual member of the structure as well as the structure itself.</p> <p>For actual source code, internally document chunks of each function, so that an someone familiar with Subversion can understand the algorithm being implemented. Do not include obvious or overly verbose documentation; the comments should help understanding of the code, not hinder it.</p> <p>For example:</p> <pre> <span style="color: red;">/*** How not to document. Don't do this. ***/</span> /* Make a foo object. */ static foo_t * make_foo_object(arg1, arg2, apr_pool_t *pool) { /* Create a subpool. */ apr_pool_t *subpool = svn_pool_create(pool); /* Allocate a foo object from the main pool */ foo_t *foo = apr_palloc(pool, sizeof(*foo)); ... } </pre> <p>Instead, document decent sized chunks of code, like this:</p> <pre> /* Transmit the segment (if its within the scope of our concern). */ SVN_ERR(maybe_crop_and_send_segment(segment, start_rev, end_rev, receiver, receiver_baton, subpool)); /* If we've set CURRENT_REV to SVN_INVALID_REVNUM, we're done (and didn't ever reach END_REV). */ if (! SVN_IS_VALID_REVNUM(current_rev)) break; /* If there's a gap in the history, we need to report as much (if the gap is within the scope of our concern). */ if (segment->range_start - current_rev < 1) { svn_location_segment_t *gap_segment; gap_segment = apr_pcalloc(subpool, sizeof(*gap_segment)); gap_segment->range_end = segment->range_start - 1; gap_segment->range_start = current_rev + 1; gap_segment->path = NULL; SVN_ERR(maybe_crop_and_send_segment(gap_segment, start_rev, end_rev, receiver, receiver_baton, subpool)); } </pre> <p>Read over the Subversion code to get an overview of how documentation looks in practice; in particular, see <a href="https://svn.apache.org/repos/asf/subversion/trunk/subversion/include/"> subversion/include/*.h</a> for doxygen examples. </p> </div>  <div class="h3" id="doxygen-docs"> <h3>Public API Documentation <a class="sectionlink" href="general.html#doxygen-docs" title="Link to this section">¶</a> </h3> <p>We use the <a href="https://www.doxygen.nl/">Doxygen</a> format for public interface documentation. This means anything that goes in a public header file. The generated documentation is <a href="/docs/#api">published on the web site</a> for the latest and some earlier Subversion sources.</p> <p>We use only a small portion of the available <a href="https://www.stack.nl/~dimitri/doxygen/commands.html">doxygen commands</a> to markup our source. When writing doxygen documentation, the following conventions apply:</p> <ul> <li>Use complete sentences and prose descriptions of the function, preceding parameter names with <code>@a</code>, and type and macro names with <code>@c</code>.</li> <li>Use <code><tt>...</tt></code> to display multiple words and <code>@p</code> to display only one word in typewriter font.</li> <li>Constant values, such as <code>TRUE</code>, <code>FALSE</code> and <code>NULL</code> should be in all caps.</li> <li>When several functions are related, define a group name, and group them together using <code>@defgroup</code> and <code>@{...@}</code>.</li> </ul> <p>See the <a href="https://www.stack.nl/~dimitri/doxygen/manual.html">Doxygen manual</a> for a complete list of commands.</p> </div>  </div>  <div class="h2" id="patches"> <h2>Patch submission guidelines <a class="sectionlink" href="general.html#patches" title="Link to this section">¶</a> </h2> <div class="h3" id="patches-writing"> <h3>Writing patches <a class="sectionlink" href="general.html#patches-writing" title="Link to this section">¶</a> </h3> <p>To get the latest source code, run:</p> <pre>svn checkout https://svn.apache.org/repos/asf/subversion/trunk/ svn-trunk</pre> <p>and follow the instructions in the <tt>INSTALL</tt> file. (If you do not have an <tt>svn</tt> client, <a href="/download.cgi">download a source tarball</a>.)</p> <p>If your patch implements a new feature, or changes large amounts of code, please remember to discuss it on the dev@ list first. Please wait some time for a response, as not everyone is online all the time. That is so the community can express concerns with and suggest improvements for the proposed feature or implementation details as soon as possible—it is always better for all parties if that feedback is provided sooner (even before any code is written) rather than later.</p> <p>If you have any questions about the patch, please feel free to ask them on dev@.</p> </div>  <div class="h3" id="patches-submission"> <h3>Submitting patches <a class="sectionlink" href="general.html#patches-submission" title="Link to this section">¶</a> </h3> <p>Mail patches to dev@subversion.apache.org, starting the subject line with <tt>[PATCH]</tt>. This helps our <a href="roles.html#patch-manager">patch manager</a> spot patches right away. For example:</p> <pre> Subject: [PATCH] fix for rev printing bug in svn status </pre> <p>If the patch addresses a particular issue, include the issue number as well: "<tt>[PATCH] issue #1729: ...</tt>". Developers who are interested in that particular issue will know to read the mail.</p> <p>A patch submission should contain one logical change; please don't mix N unrelated changes in one submission — send N separate emails instead.</p> <p>Generate the patch using <tt>svn diff -x-p</tt> from the top of a Subversion trunk working copy. If the file you're diffing is not under revision control, you can achieve the same effect by using <tt>diff -u</tt>.</p> <p>Please include a log message with your patch. A good log message helps potential reviewers understand the changes in your patch, and increases the likelihood that it will be applied. You can put the log message in the body of the email, or at the top of the patch attachment (see below). Either way, it should follow the guidelines given in <a href="conventions.html#log-messages">Writing log messages</a>, and be enclosed in triple square brackets, like so:</p> <pre> [[[ Fix issue #1729: Don't crash because of a missing file. * subversion/libsvn_ra_ansible/get_editor.c (frobnicate_file): Check that file exists before frobnicating. ]]] </pre> <p>(The brackets are not actually part of the log message, they're just a way to clearly mark off the log message from its surrounding context.)</p> <p>If possible, send the patch as an attachment with a mime-type of <code>text/x-diff</code>, <code>text/x-patch</code>, or <code>text/plain</code>. Most people's mailreaders can display those inline, and having the patch as an attachment allows them to extract the patch from the message conveniently. Never send patches in archived or compressed form (e.g., tar, gzip, zip, bzip2), because that prevents people from reviewing the patch directly in their mailreaders.</p> <p>If you can't attach the patch with one of these mime-types, or if the patch is very short, then it's okay to include it directly in the body of your message. But watch out: some mail editors munge inline patches by inserting unasked-for line breaks in the middle of long lines. If you think your mail software might do this, then please use an attachment instead.</p> <p>If the patch implements a new feature, make sure to describe the feature completely in your mail; if the patch fixes a bug, describe the bug in detail and give a reproduction recipe. An exception to these guidelines is when the patch addresses a specific issue in the issues database — in that case, just refer to the issue number in your log message, as described in <a href="conventions.html#log-messages">Writing log messages</a>.</p> <p>It is normal for patches to undergo several rounds of feedback and change before being applied. Don't be discouraged if your patch is not accepted immediately — it doesn't mean you goofed, it just means that there are a <em>lot</em> of eyes looking at every code submission, and it's a rare patch that doesn't have at least a little room for improvement. After discussing people's responses to your patch, make the appropriate changes and resubmit, wait for the next round of feedback, and lather, rinse, repeat, until some committer applies it. You can avoid some iterations by reviewing and applying the project's <a href="conventions.html">Coding Conventions</a> to your patch before submitting it.</p> <p>If you don't get a response for a while, and don't see the patch applied, it may just mean that people are really busy. Go ahead and repost, and don't hesitate to point out that you're still waiting for a response. One way to think of it is that patch management is highly parallizable, and we need you to shoulder your share of the management as well as the coding. Every patch needs someone to shepherd it through the process, and the person best qualified to do that is the original submitter.</p> </div>  </div>  </div>  </div>  </body> </html>