You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@subversion.apache.org by cm...@apache.org on 2010/02/12 22:17:55 UTC
svn commit: r909607 [2/3] - /subversion/site/publish/docs/community-guide/
Modified: subversion/site/publish/docs/community-guide/index.html
URL: http://svn.apache.org/viewvc/subversion/site/publish/docs/community-guide/index.html?rev=909607&r1=909606&r2=909607&view=diff
==============================================================================
--- subversion/site/publish/docs/community-guide/index.html (original)
+++ subversion/site/publish/docs/community-guide/index.html Fri Feb 12 21:17:52 2010
@@ -2,4916 +2,25 @@
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
-<title>Subversion Community Guide</title>
+<title>Apache Subversion - Community Guide - General Overview</title>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
<style type="text/css">
-body {
- font-family: Tahoma, Arial, sans-serif;
- font-size: 10pt;
- line-height: 1.2em;
-}
-pre {
- font-size: 90%;
-}
-h1, h2, h3, h4 {
- margin-top: 1.5em;
-}
-.h1 {
- border-top: 1px black solid;
-}
-.h2, .h3, .h4 {
- margin-left: 0.5in;
-}
-#toc, #toc ol {
- list-style: none;
-}
-.todo {
- margin-left: 0.5in;
- margin-right: 0.5in;
- padding: 1em;
- border: 2px red solid;
-}
+ @import url("/style/site.css");
</style>
</head>
<body>
+<!--#include virtual="/site-banner.html" -->
+<!--#include virtual="/site-nav.html" -->
+<div id="site-content">
+<!--#include virtual="/site-notice.html" -->
+<!--#include virtual="guide-nav.html" -->
<h1>Subversion Community Guide (aka "HACKING")</h1>
<p>If you are contributing to the Subversion project, please read this
first.</p>
-<!-- Other pages seem to use "h2" for ToC, but I think "h1" works
- better, because the ToC is fundamentally different from other
- sections and therefore it's confusing when it looks the same as
- the others. -->
-<div class="h1"><!-- no 'id' or 'title' attribute for ToC -->
-<h1>Table of Contents</h1>
-
-<ol id="toc">
- <li><a href="#general">General Overview</a>
- <ol>
- <li><a href="#participating">Participating in the community</a></li>
- <li><a href="#docs">Theory and documentation</a></li>
- <li><a href="#code-to-read">Code to read</a></li>
- <li><a href="#directory-layout">Directory layout</a></li>
- <li><a href="#branch-policy">Branch policy</a></li>
- <li><a href="#documenting">Documentation</a></li>
- <li><a href="#patches">Patch submission guidelines</a></li>
- </ol>
- </li>
- <li><a href="#roles">Community Roles</a>
- <ol>
- <li><a href="#committers">Committers</a></li>
- <li><a href="#release-manager">Release Manager</a></li>
- <li><a href="#patch-manager">Patch Manager</a></li>
- </ol>
- </li>
- <li><a href="#conventions">Coding and Commit Conventions</a>
- <ol>
- <li><a href="#interface-visibility">Code modularity and interface visibility</a></li>
- <li><a href="#coding-style">Coding style</a></li>
- <li><a href="#use-page-breaks">Using page breaks</a></li>
- <li><a href="#error-messages">Error message conventions</a></li>
- <li><a href="#apr-pools">APR pool usage conventions</a></li>
- <li><a href="#apr-status-codes">APR status codes</a></li>
- <li><a href="#exception-handling">Exception handling</a></li>
- <li><a href="#secure-coding">Secure coding guidelines</a></li>
- <li><a href="#destruction-of-stacked-resources">Destruction of stacked resources</a></li>
- <li><a href="#other-conventions">Other coding conventions</a></li>
- <li><a href="#log-messages">Writing log messages</a></li>
- <li><a href="#crediting">Crediting</a></li>
- </ol>
- </li>
- <li><a href="#building-and-testing">Building and Testing</a>
- <ol>
- <li><a href="#configury">The configuration/build system under unix</a></li>
- <li><a href="#automated-tests">Automated tests</a></li>
- <li><a href="#build-farm">Build farm</a></li>
- <li><a href="#write-test-cases-first">Writing test cases before code</a></li>
- </ol>
- </li>
- <li><a href="#debugging">Debugging Subversion</a>
- <ol>
- <li><a href="#server-debugging">Debugging the server</a></li>
- <li><a href="#net-trace">Tracing network traffic</a></li>
- <li><a href="#tracing-memory-leaks">Tracking down memory leaks</a></li>
- </ol>
- </li>
- <li><a href="#mailing-lists">Mailing Lists</a>
- <ol>
- <li><a href="#where-to-post">Where to post</a></li>
- <li><a href="#when-to-post">When to post</a></li>
- <li><a href="#formatting">Formatting</a></li>
- <li><a href="#replying">Replying</a></li>
- <li><a href="#sending-patches">Sending patches</a></li>
- <li><a href="#encodings">Languages and encodings</a></li>
- </ol>
- </li>
- <li><a href="#issues">Bugs / Issues</a>
- <ol>
- <li><a href="#reporting-bugs">How to report a bug</a></li>
- <li><a href="#bugs-where">Where to report a bug</a></li>
- <li><a href="#issue-triage">Issue triage</a></li>
- </ol>
- </li>
- <li><a href="#releasing">Making Subversion Releases</a>
- <ol>
- <li><a href="#release-numbering">Release numbering, compatibility, and deprecation</a></li>
- <li><a href="#release-stabilization">Stabilizing and maintaining releases</a></li>
- <li><a href="#tarball-signing">Signing source distribution packages (a.k.a tarballs)</a></li>
- <li><a href="#custom-releases">Custom releases</a></li>
- <li><a href="#release-branches">Creating and maintaining release branches</a></li>
- <li><a href="#porting-changes">Porting changes to release branches</a></li>
- <li><a href="#the-changes-file">Managing the CHANGES file</a></li>
- <li><a href="#before-release">Preparing to roll a release</a></li>
- <li><a href="#rolling-release">Rolling a release</a></li>
- <li><a href="#releasing-release">The actual releasing</a></li>
- <li><a href="#afterwards">After a release has been made</a></li>
- <li><a href="#releasing-not">How <em>not</em> to make a Subversion release</a></li>
- </ol>
- </li>
- <li><a href="#l10n">Localization (l10n)</a>
- <ol>
- <li><a href="#l10n-overview">Localization overview</a></li>
- <li><a href="#version-requirements">Software version requirements</a></li>
- <li><a href="#new-translation">Starting a new translation</a></li>
- <li><a href="#verifying">Verifying your po file</a></li>
- <li><a href="#submitting">Submitting your po file</a></li>
- <li><a href="#updating">Updating existing po files</a></li>
- <li><a href="#branch-maintenance">Maintenance on branches</a></li>
- <li><a href="#po-mo-requirements">Requirements for po and mo files</a></li>
- <li><a href="#empty-string-conventions">Conventions for the empty string msgid section</a></li>
- <li><a href="#translation-teams">Translation teams</a></li>
- <li><a href="#quotes">Single versus double quotes</a></li>
- <li><a href="#translating-error-messages">Error message conventions</a></li>
- </ol>
- </li>
-</ol>
-
-</div>
-
-<div class="h1" id="general">
-<h1>General Overview
- <a class="sectionlink" href="#general"
- title="Link to this section">¶</a>
-</h1>
-
-<div class="h2" id="participating">
-<h2>Participating in the community
- <a class="sectionlink" href="#participating"
- title="Link to this section">¶</a>
-</h2>
-
-<p>Although Subversion was originally sponsored and hosted by
-CollabNet (<a href="http://www.collab.net">http://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>
-
-<p>Go to <a href="http://subversion.apache.org/"
->http://subversion.apache.org/</a> and</p>
-
-<ul>
-<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.</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>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="http://subversion.tigris.org/issue-tracker.html"
- >http://subversion.tigris.org/issue-tracker.html</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
-svn-breakage@subversion.tigris.org mailing list. See more details at
-<a href="http://subversion.tigris.org/servlets/ProjectMailingListList"
- >http://subversion.tigris.org/servlets/ProjectMailingListList</a>
-in the description for the svn-breakage list.</p>
-
-</div> <!-- participating -->
-
-
-<div class="h2" id="docs">
-<h2>Theory and documentation
- <a class="sectionlink" href="#docs"
- title="Link to this section">¶</a>
-</h2>
-
-<ol>
-<li><p>Design</p>
-
- <p>A <a href="http://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="#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 href="http://beautifulcode.oreillynet.com/">
- Beautiful Code: Leading Programmers Explain How They Think</a>
- covering the design and use of
- <a href="http://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="http://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="http://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="http://svnbook.red-bean.com"
- >http://svnbook.red-bean.com</a>. The XML source and
- translations to other languages are maintained in their own
- repository at <a href="http://svn.red-bean.com/svnbook"
- >http://svn.red-bean.com/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="http://svn.apache.org/repos/asf/subversion/trunk/notes/"
- >notes/</a> directory.</p>
-</li>
-
-</ol>
-
-</div> <!-- docs -->
-
-
-<div class="h2" id="code-to-read">
-<h2>Code to read
- <a class="sectionlink" href="#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: svn_string.h, svn_error.h, svn_types.h</p>
-</li>
-<li><p>useful utilities: svn_io.h, svn_path.h, svn_hash.h, svn_xml.h</p>
-</li>
-<li><p>the critical interface: svn_delta.h</p>
-</li>
-<li><p>client-side interfaces: svn_ra.h, svn_wc.h, svn_client.h</p>
-</li>
-<li><p>the repository and versioned filesystem: svn_repos.h, svn_fs.h</p>
-</li>
-</ol>
-
-<p>Subversion tries to stay portable by using
-only <a href="http://en.wikipedia.org/wiki/ANSI_C">ANSI/ISO C</a>
-(a.k.a <a href="http://en.wikipedia.org/wiki/ANSI_C#C90">C90</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="http://apr.apache.org/"
->http://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: apr_pools.h</p></li>
-<li><p>filesystem access: apr_file_io.h</p></li>
-<li><p>hashes and arrays: apr_hash.h, apr_tables.h</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 'notes/assurance.txt'). 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> <!-- code-to-read -->
-
-
-<div class="h2" id="directory-layout">
-<h2>Directory layout
- <a class="sectionlink" href="#directory-layout"
- title="Link to this section">¶</a>
-</h2>
-
-<p>A rough guide to the source tree:</p>
-
-<ul>
-<li><p><tt>doc/</tt><br />
- User and Developer documentation.</p>
-</li>
-<li><p><tt>tools/</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>contrib/</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>packages/</tt><br />
- Stuff to help packaging systems, like rpm and dpkg.</p>
-</li>
-<li><p><tt>subversion/</tt><br />
- Source code to Subversion itself (as opposed to external
- libraries).</p>
-</li>
-<li><p><tt>subversion/include/</tt><br />
- Public header files for users of Subversion libraries.</p>
-</li>
-<li><p><tt>subversion/include/private/</tt><br />
- Private header files shared internally by Subversion libraries.</p>
-</li>
-<li><p><tt>subversion/libsvn_fs/</tt><br />
- The versioning "filesystem" API.</p>
-</li>
-<li><p><tt>subversion/libsvn_repos/</tt><br />
- Repository functionality built around the `libsvn_fs' core.</p>
-</li>
-<li><p><tt>subversion/libsvn_delta/</tt><br />
- Common code for tree deltas, text deltas, and property deltas.</p>
-</li>
-<li><p><tt>subversion/libsvn_wc/</tt><br />
- Common code for working copies.</p>
-</li>
-<li><p><tt>subversion/libsvn_ra/</tt><br />
- Common code for repository access.</p>
-</li>
-<li><p><tt>subversion/libsvn_client/</tt><br />
- Common code for client operations.</p>
-</li>
-<li><p><tt>subversion/svn/</tt><br />
- The command line client.</p>
-</li>
-<li><p><tt>subversion/tests/</tt><br />
- Automated test suite.</p>
-</li>
-<li><p><tt>apr/</tt><br />
- Apache Portable Runtime library. (Note: This is not in the same
- repository as Subversion. Read INSTALL for instructions on how to
- get it if you don't already have it.)</p>
-</li>
-<li><p><tt>neon/</tt><br />
- Neon library from Joe Orton. (Note: This is not in the same
- repository as Subversion. Read INSTALL for instructions on how to
- get it if you don't already have it.)</p>
-</li>
-</ul>
-
-</div> <!-- directory-layout -->
-
-
-<div class="h2" id="branch-policy">
-<h2>Branching policy
- <a class="sectionlink" href="#branch-policy"
- title="Link to this section">¶</a>
-</h2>
-
-<p>The Subversion project strongly prefers that active development
-happen 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="#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>
-
-</div> <!-- branch-creation-and-management -->
-
-<div class="h3" id="lightweight-branches">
-<h3>Lightweight branches
- <a class="sectionlink" href="#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.</p>
-
-<p>If you're just using the branch to "checkpoint" your code, and
-don't feel it's ready for review, please put some sort of notice at
-the top of the log message, such as:</p>
-
-<pre>
- *** checkpoint commit -- please don't waste your time reviewing it ***
-</pre>
-
-<p>And if a later commit on that branch <em>should</em> be reviewed,
-then please supply, in the log message, the appropriate 'svn diff'
-command, since the diff would likely involve two non-adjacent commits
-on that branch, and reviewers shouldn't have to spend time figuring
-out which ones they are.</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="#partial-commit-access" >section on partial
-commit access</a> for our policy on offering commit access to
-experimental branches.</p>
-
-</div> <!-- lightweight-branches -->
-
-<div class="h3" id="branch-readme-files">
-<h3>BRANCH-README files
- <a class="sectionlink" href="#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
- reintegrate-able branch that will regularly be kept in sync
- with its source branch and ultimately merged back to that
- source branch using <tt>svn merge --reintegrate</tt>? Or is it
- not reintegrate-able, managed in total disregard to new changes
- made to the source branch, and expected to be merged back to
- that source without the <tt>--reintegrate</tt> option <tt>svn
- merge</tt>?</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 being
-managed as a reintegrate-able branch, with regular catch-up merges
-from the trunk.
-
-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> <!-- branch-readme-files -->
-
-</div> <!-- branch-policy -->
-
-
-<div class="h2" id="documenting">
-<h2>Documentation
- <a class="sectionlink" href="#documenting"
- title="Link to this section">¶</a>
-</h2>
-
-<div class="h3" id="document-everything">
-<h3>Document Everything
- <a class="sectionlink" href="#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="http://svn.apache.org/repos/asf/subversion/trunk/subversion/include/">
-subversion/include/*.h</a> for doxygen examples.
-</p>
-
-</div> <!-- document-everything -->
-
-<div class="h3" id="doxygen-docs">
-<h3>Public API Documentation
- <a class="sectionlink" href="#doxygen-docs"
- title="Link to this section">¶</a>
-</h3>
-
-<p>We use the <a href="http://www.doxygen.org/">Doxygen</a> format for
-public interface documentation. This means anything that goes in a
-public header file. <a href="http://svn.collab.net/svn-doxygen/">Snapshots
-</a> of the public API documentation are generated nightly from the latest
-Subversion sources.</p>
-
-<p>We use only a small portion of the available
-<a href="http://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="http://www.stack.nl/~dimitri/doxygen/manual.html">Doxygen
-manual</a> for a complete list of commands.</p>
-
-</div> <!-- doxygen-docs -->
-
-</div> <!-- documenting -->
-
-<div class="h2" id="patches">
-<h2>Patch submission guidelines
- <a class="sectionlink" href="#patches"
- title="Link to this section">¶</a>
-</h2>
-
-<p>Mail patches to dev@subversion.apache.org, starting the subject
-line with <tt>[PATCH]</tt>. This helps our patch manager 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</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="#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="#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 reading 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.</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> <!-- patches -->
-
-</div> <!-- general -->
-
-
-<div class="h1" id="roles">
-<h1>Community Roles
- <a class="sectionlink" href="#roles"
- title="Link to this section">¶</a>
-</h1>
-
-<div class="h2" id="committers">
-<h2>Committers
- <a class="sectionlink" href="#committers"
- title="Link to this section">¶</a>
-</h2>
-
-<p>Committers in the Subversion project are those folks to whom the
-right to directly commit changes to our version controlled resources
-has been granted. The project is meritocratic, which means (among
-other things) that project governance is handled by those who do the
-work. There are two types of commit access: full and partial. Full
-means anywhere in the tree, partial means only in that committer's
-specific area(s) of expertise. While every contribution is valued
-regardless of its source, not every person who contributes code to
-Subversion will earn commit access.</p>
-
-<p>The <a href="http://svn.apache.org/repos/asf/subversion/trunk/COMMITTERS"
->COMMITTERS</a> file lists all committers, both full and partial, and
-says the domains for each partial committer.</p>
-
-<div class="h3" id="full-commit-access">
-<h3>How full commit access is granted
- <a class="sectionlink" href="#full-commit-access"
- title="Link to this section">¶</a>
-</h3>
-
-<p>After someone has successfully contributed a few non-trivial
-patches, some full committer, usually whoever has reviewed and applied
-the most patches from that contributor, proposes them for commit
-access. This proposal is sent only to the other full committers --
-the ensuing discussion is private, so that everyone can feel
-comfortable speaking their minds. Assuming there are no objections,
-the contributor is granted commit access. The decision is made by
-consensus; there are no formal rules governing the procedure, though
-generally if someone strongly objects the access is not offered, or is
-offered on a provisional basis.</p>
-
-<p><i>The primary criterion for full commit access is good
-judgment.</i></p>
-
-<p>You do not have to be a technical wizard, or demonstrate deep
-knowledge of the entire codebase, to become a full committer. You
-just need to know what you don't know. If your patches adhere to the
-guidelines in this file, adhere to all the usual unquantifiable rules
-of coding (code should be readable, robust, maintainable, etc.), and
-respect the Hippocratic Principle of "first, do no harm", then you
-will probably get commit access pretty quickly. The size, complexity,
-and quantity of your patches do not matter as much as the degree of
-care you show in avoiding bugs and minimizing unnecessary impact on
-the rest of the code. Many full committers are people who have not
-made major code contributions, but rather lots of small, clean fixes,
-each of which was an unambiguous improvement to the code. (Of course,
-this does not mean the project needs a bunch of very trivial patches
-whose only purpose is to gain commit access; knowing what's worth a
-patch post and what's not is part of showing good judgement :-) .)</p>
-
-<p>To assist developers in discovering new committers, we record
-patches and other contributions in a <a href="#crediting">special
-crediting format</a>, which is then parsed to produce a
-browser-friendly <a
-href="http://www.red-bean.com/svnproject/contribulyzer/">contribution
-list</a>, updated nightly. If you're thinking of proposing someone
-for commit access and want to look over all their changes, that <a
-href="http://www.red-bean.com/svnproject/contribulyzer/">contribution
-list</a> might be the most convenient place to do it.</p>
-
-</div> <!-- full-commit-access -->
-
-<div class="h3" id="partial-commit-access">
-<h3>How partial commit access is granted
- <a class="sectionlink" href="#partial-commit-access"
- title="Link to this section">¶</a>
-</h3>
-
-<p>A full committer sponsors the partial committer. Usually this
-means the full committer has applied several patches to the same area
-from the proposed partial committer, and realizes things would be
-easier if the person were just committing directly. Approval is not
-required from the full committers; it is assumed that sponsors know
-what they're doing and will watch the partial committer's first few
-commits to make sure everything's going smoothly.</p>
-
-<p>Patches submitted by a partial committer may be committed by that
-committer even if they are outside that person's domain. This
-requires approval (often expressed as a +1 vote) from at least one
-full committer. In such a case, the approval should be noted in the
-log message, like so:</p>
-
-<pre>
- Approved by: lundblad
-</pre>
-
-<p>Any full committer may offer anyone commit access to an
-experimental branch at any time. It is not necessary that the
-experimental branch have a high likelihood of being merged to trunk
-(although that's always a good goal to aim for). It's just as
-important that the full committer — all the full
-committers, actually — view such branches as training
-grounds for new developers, by giving feedback on the commits. The
-goal of these branches is both to get new code into Subversion and to
-get new developers into the project. See also the <a
-href="#lightweight-branches" >section on lightweight branches</a>, and
-this mail:</p>
-
-<pre>
- <a href="http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgNo=132746"
->http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgNo=132746</a>
- From: Karl Fogel <kfogel@red-bean.com>
- To: dev@subversion.tigris.org
- Subject: branch liberalization (was: Elego tree conflicts work)
- Date: Tue, 20 Nov 2007 10:49:38 -0800
- Message-Id: <87y7cswy4d.fsf@red-bean.com>
-</pre>
-
-</div> <!-- partial-commit-access -->
-
-<div class="h3" id="contrib-area">
-<h3>The contrib/ area
- <a class="sectionlink" href="#contrib-area"
- title="Link to this section">¶</a>
-</h3>
-
-<p>When a tool is accepted into the <i>contrib/</i> area, we
-automatically offer its author partial commit access to maintain the
-tool there. Any full committer can sponsor this. Usually no
-discussion or vote is necessary, though if there are objections then
-the usual decision-making procedures apply (attempt to reach consensus
-first, then vote among the full committers if consensus cannot be
-reached).</p>
-
-<p>Code under contrib/ must be open source, but need not have the same
-license or copyright holder as Subversion itself.</p>
-
-</div> <!-- contrib-area -->
-
-<div class="h3" id="obvious-fix">
-<h3>The "obvious fix" rule
- <a class="sectionlink" href="#obvious-fix"
- title="Link to this section">¶</a>
-</h3>
-
-<p>Any committer, whether full or partial, may commit fixes for
-obvious typos, grammar mistakes, and formatting problems wherever they
-may be — in the web pages, API documentation, code
-comments, commit messages, etc. We rely on the committer's judgement
-to determine what is "obvious"; if you're not sure, just ask.</p>
-
-<p>Whenever you invoke the "obvious fix" rule, please say so in
-the <a href="#log-messages">log message</a> of your commit. For example:</p>
-
-<pre>
-------------------------------------------------------------------------
-r32135 | stylesen | 2008-07-16 10:04:25 +0200 (Wed, 16 Jul 2008) | 8 lines
-
-Update "check-license.py" so that it can generate license text applicable
-to this year.
-
-Obvious fix.
-
-* tools/dev/check-license.py
- (NEW_LICENSE): s/2005/2008/
-
-------------------------------------------------------------------------
-</pre>
-
-</div> <!-- obvious-fix -->
-
-</div> <!-- committers -->
-
-
-<div class="h2" id="release-manager">
-<h2>Release Manager
- <a class="sectionlink" href="#release-manager"
- title="Link to this section">¶</a>
-</h2>
-
-<p>The role of the Release Manager in the Subversion project is to
-handle the process of getting code stabilized, packaged and released
-to the general public. If we were building planes, the RM would be
-the guy looking at the construction checklists, painting the airline
-logo on the fuselage, and delivering the finished unit to the
-customer.</p>
-
-<p>As such, there is no real development associated with being an RM.
-All the work you have to do is non-coding: coordinating people,
-centralizing information, and being the public voice announcing new
-stable releases. A lot of the tasks that the RM has to do are
-repetitive, and not automated either because nobody has broken down
-and written the tools yet, or because the tasks require human
-validation that makes automation a little superfluous.</p>
-
-<p>You may be thinking at this stage that the RM's duty is
-unglamorous, and you are kinda right. If you are looking for a
-position within the project that will bring fame and fortune, you're
-better off implementing stuff that really needs to be done on trunk.
-If you're looking for something that really helps people who don't
-care about releases focus on code, then RMing is for you.</p>
-
-<p>So, you are the Release Manager. What do you need to do? This is
-what the rest of this document is about.</p>
-
-</div> <!-- release-manager -->
-
-
-<div class="h2" id="patch-manager">
-<h2>Patch Manager
- <a class="sectionlink" href="#patch-manager"
- title="Link to this section">¶</a>
-</h2>
-
-<p>Subversion usually has a Patch Manager, whose job is to watch the
-dev@ mailing list and make sure that no patches "slip through the
-cracks".</p>
-
-<p>This means watching every thread containing "[PATCH]" mails, and
-taking appropriate action based on the progress of the thread. If the
-thread resolves on its own (because the patch gets committed, or
-because there is consensus that the patch doesn't need to be applied,
-or whatever) then no further action need be taken. But if the thread
-fades out without any clear decision, then the patch needs to be saved
-in the issue tracker. This means that a summary of any discussion
-threads around that patch, and links to relevant mailing list
-archives, will be added to some issue in the tracker. For a patch
-which addresses an existing issue tracker item, the patch is saved to
-that item. Otherwise, a new issue of type 'PATCH' is filed, and the
-patch is saved to that new issue.</p>
-
-<p>The Patch Manager needs a basic technical understanding of
-Subversion, and the ability to skim a thread and get a rough
-understanding of whether consensus has been reached, and if so, of
-what kind. It does <em>not</em> require actual Subversion development
-experience or commit access. Expertise in using one's mail reading
-software is optional, but recommended :-).</p>
-
-<p>The current patch manager is Gavin 'Beau' Baumanis
-<gavin@thespidernet.com>.</p>
-
-</div> <!-- patch-manager -->
-
-</div> <!-- roles -->
-
-
-<div class="h1" id="conventions">
-<h1>Coding and Commit Conventions
- <a class="sectionlink" href="#conventions"
- title="Link to this section">¶</a>
-</h1>
-
-<div class="h2" id="interface-visibility">
-<h2>Code modularity and interface visibility
- <a class="sectionlink" href="#interface-visibility"
- title="Link to this section">¶</a>
-</h2>
-
-<p>Subversion's code and headers files are segregated along a couple
-of key lines: library-specific vs. inter-library; public vs. private.
-This separation is done primarily because of our focus on proper
-modularity and code organization, but also because of our promises as
-providers and maintainers of a widely adopted public API. As you
-write new functions in Subversion, you'll need to carefully consider
-these things, asking some questions of yourself as you go along:</p>
-
-<p><em>"Are the consumers of my new code local to a particular source
-code file in a single library?"</em> If so, you probably want a static
-function in that same source file.</p>
-
-<p><em>"Is my new function of the sort that other source code within
-this library will need to use, but nothing *outside* the library?"</em>
-If so, you want to use a non-static, double-underscore-named function
-(such as <tt>svn_foo__do_something</tt>), with its prototype in the
-appropriate library-specific header file.</p>
-
-<p><em>"Will my code need to be accessed from a different
-library?"</em> Here you have some additional questions to answer, such
-as <em>"Should my code live in the original library I was going to put
-it in, or should it live in a more generic utility library such as
-libsvn_subr?"</em> Either way, you're now looking at using an
-inter-library header file. But see the next question before you decide
-which one...</p>
-
-<p><em>"Is my code such that it has a clean, maintainable API that can
-reasonably be maintained in perpetuity and brings value to the
-Subversion public API offering?"</em> If so, you'll be adding
-prototypes to the public API, immediately
-inside <tt>subversion/include/</tt>. If not, double-check your plans
--- maybe you haven't chosen the best way to abstract your
-functionality. But sometimes it just happens that libraries need to
-share some function that is arguably of no use to other software
-besides Subversion itself. In those cases, use the private header
-files in <tt>subversion/include/private/</tt>.</p>
-
-</div> <!-- interface-visibility -->
-
-<div class="h2" id="coding-style">
-<h2>Coding style
- <a class="sectionlink" href="#coding-style"
- title="Link to this section">¶</a>
-</h2>
-
-<p>Subversion uses ANSI C, and follows the GNU coding standards,
-except that we do not put a space between the name of a function and
-the opening parenthesis of its parameter list. Emacs users can just
-load svn-dev.el to get the right indentation behavior (most source
-files here will load it automatically, if `enable-local-eval' is set
-appropriately).</p>
-
-<p>Read <a href="http://www.gnu.org/prep/standards.html"
->http://www.gnu.org/prep/standards.html</a> for a full description of
-the GNU coding standards. Below is a short example demonstrating the
-most important formatting guidelines, including our
-no-space-before-param-list-paren exception:</p>
-
-<pre>
- char * /* func type on own line */
- argblarg(char *arg1, int arg2) /* func name on own line */
- { /* first brace on own line */
- if ((some_very_long_condition && arg2) /* indent 2 cols */
- || remaining_condition) /* new line before operator */
- { /* brace on own line, indent 2 */
- arg1 = some_func(arg1, arg2); /* NO SPACE BEFORE PAREN */
- } /* close brace on own line */
- else
- {
- do /* format do-while like this */
- {
- arg1 = another_func(arg1);
- }
- while (*arg1);
- }
- }
-</pre>
-
-<p>In general, be generous with parentheses even when you're sure
-about the operator precedence, and be willing to add spaces and
-newlines to avoid "code crunch". Don't worry too much about vertical
-density; it's more important to make code readable than to fit that
-extra line on the screen.</p>
-
-</div> <!-- coding-style -->
-
-
-<div class="h2" id="use-page-breaks">
-<h2>Using page breaks
- <a class="sectionlink" href="#use-page-breaks"
- title="Link to this section">¶</a>
-</h2>
-
-<p>We're using page breaks (the Ctrl-L character, ASCII 12) for
-section boundaries in both code and plaintext prose files. Each
-section starts with a page break, and immediately after the page break
-comes the title of the section.</p>
-
-<p>This helps out people who use the Emacs page commands, such as
-`pages-directory' and `narrow-to-page'. Such people are not as scarce
-as you might think, and if you'd like to become one of them, then add
-(require 'page-ext) to your .emacs and type C-x C-p C-h sometime.</p>
-
-</div> <!-- use-page-breaks -->
-
-
-<div class="h2" id="error-messages">
-<h2>Error message conventions
- <a class="sectionlink" href="#error-messages"
- title="Link to this section">¶</a>
-</h2>
-
-<p>For error messages the following conventions apply:</p>
-
-<ul>
-
-<li><p>Provide specific error messages only when there is information
- to add to the general error message found in
- subversion/include/svn_error_codes.h.</p></li>
-
-<li><p>Messages start with a capital letter.</p></li>
-
-<li><p>Try keeping messages below 70 characters.</p></li>
-
-<li><p>Don't end the error message with a period (".").</p></li>
-
-<li><p>Don't include newline characters in error messages.</p></li>
-
-<li><p>Quoting information is done using single quotes (e.g. "'some info'").</p></li>
-
-<li><p>Don't include the name of the function where the error occurs
- in the error message. If Subversion is compiled using the
- '--enable-maintainer-mode' configure-flag, it will provide this
- information by itself.</p></li>
-
-<li><p>When including path or filenames in the error string, be sure
- to quote them (e.g. "Can't find '/path/to/repos/userfile'").</p></li>
-
-<li><p>When including path or filenames in the error string, be sure
- to convert them using <a
- href="http://svn.collab.net/svn-doxygen/svn__path_8h.html#a1"
- ><tt>svn_path_local_style()</tt></a> before inclusion (since
- paths passed to and from Subversion APIs are assumed to be
- in <a href="http://svn.collab.net/svn-doxygen/svn__path_8h.html#a0"
- >canonical form</a>).</p></li>
-
-<li><p>Don't use Subversion-specific abbreviations (e.g. use "repository"
- instead of "repo", "working copy" instead of "wc").</p></li>
-
-<li><p>If you want to add an explanation to the error, report it
- followed by a colon and the explanation like this:</p>
- <pre>
- "Invalid " SVN_PROP_EXTERNALS " property on '%s': "
- "target involves '.' or '..'".
- </pre></li>
-
-<li><p>Suggestions or other additions can be added after a semi-colon,
- like this:</p>
- <pre>
- "Can't write to '%s': object of same name already exists; remove "
- "before retrying".
- </pre></li>
-
-<li><p>Try to stay within the boundaries of these conventions, so please avoid
- separating different parts of error messages by other separators such
- as '--' and others.</p></li>
-
-</ul>
-
-<p>Also read about <a href="#l10n">Localization</a>.</p>
-
-</div> <!-- error-messages -->
-
-
-<div class="h2" id="apr-pools">
-<h2>APR pool usage conventions
- <a class="sectionlink" href="#apr-pools"
- title="Link to this section">¶</a>
-</h2>
-
-<p>(This assumes you already basically understand how APR pools work;
-see apr_pools.h for details.)</p>
-
-<p>Applications using the Subversion libraries must call
-apr_initialize() before calling any Subversion functions.</p>
-
-<p>Subversion's general pool usage strategy can be summed up in two
-principles:</p>
-
-<ol>
-<li><p>The call level that created a pool is the only place to clear or
- destroy that pool.</p>
-</li>
-<li><p>When iterating an unbounded number of times, create a subpool
- before entering the iteration, use it inside the loop and clear
- it at the start of each iteration, then destroy it after the loop
- is done, like so:</p>
- <pre>
- apr_pool_t *iterpool = svn_pool_create(scratch_pool);
-
- for (i = 0; i < n; ++i)
- {
- svn_pool_clear(iterpool);
- do_operation(..., iterpool);
- }
-
- svn_pool_destroy(iterpool);
- </pre>
-</li>
-</ol>
-
-<p>Supporting the above rules, we use the following pool names as conventions
-to represent various pool lifetimes:</p>
-<ul>
-<li><p><code>result_pool</code>: The pool in which the output of a function
-should be allocated. A result pool declaration should <strong>always</strong>
-be found in a function argument list, and never inside a local block. (But
-not all functions need or have result pools.)
-</p></li>
-
-<li><p><code>scratch_pool</code>: The pool in which all function-local data
-should be allocated. This pool is also provided by the caller, who may
-choose to clear this pool immediately when control returns to it.
-</p></li>
-
-<li><p><code>iterpool</code>: An <em>iteration</em> pool, used inside loops,
-as per the above example.</p></li>
-</ul>
-
-<p>(Note: Some legacy code uses a single <code>pool</code> function argument,
-which operates as both the result and scratch pools.)</p>
-
-<p>By using an iterpool for loop-bounded data, you ensure O(1) instead
-of O(N) memory leakage should the function return abruptly from
-within the loop (say, due to error). That's why you shouldn't make a
-subpool for data which persists throughout a function, but instead
-should use the pool passed in by the caller. That memory will be
-reclaimed when the caller's pool is cleared or destroyed. If the
-caller is invoking the callee in a loop, then trust the caller to take
-care of clearing the pool on each iteration. The same logic
-propagates all the way up the call stack.</p>
-
-<p>The pool you use also helps readers of the code understand object
-lifetimes. Is a given object used only during one iteration of the
-loop, or will it need to last beyond the end of the loop? For
-example, pool choices indicate a lot about what's going on in this
-code:</p>
-
-<pre>
- apr_hash_t *persistent_objects = apr_hash_make(result_pool);
- apr_pool_t *iterpool = svn_pool_create(scratch_pool);
-
- for (i = 0; i < n; ++i)
- {
- const char *intermediate_result;
- const char *key, *val;
-
- svn_pool_clear(iterpool);
- SVN_ERR(do_something(&intermediate_result, ..., iterpool));
- SVN_ERR(get_result(intermediate_result, &key, &val, ...,
- result_pool));
- apr_hash_set(persistent_objects, key, APR_HASH_KEY_STRING, val);
- }
-
- svn_pool_destroy(iterpool);
- return persistent_objects;
-</pre>
-
-<p>Except for some legacy code, which was written before these
-principles were fully understood, virtually all pool usage in
-Subversion follows the above guidelines.</p>
-
-<p>One such legacy pattern is a tendency to allocate an object inside
-a pool, store the pool in the object, and then free that pool (either
-directly or through a close_foo() function) to destroy the object.</p>
-
-<p>For example:</p>
-
-<pre>
- <span style="color: red;">/*** Example of how NOT to use pools. Don't be like this. ***/</span>
-
- static foo_t *
- make_foo_object(arg1, arg2, apr_pool_t *pool)
- {
- apr_pool_t *subpool = svn_pool_create(pool);
- foo_t *foo = apr_palloc(subpool, sizeof(*foo));
-
- foo->field1 = arg1;
- foo->field2 = arg2;
- foo->pool = subpool;
- }
-
- [...]
-
- [Now some function calls make_foo_object() and returns, passing
- back a new foo object.]
-
- [...]
-
- [Now someone, at some random call level, decides that the foo's
- lifetime is over, and calls svn_pool_destroy(foo->pool).]
-</pre>
-
-<p>This is tempting, but it defeats the point of using pools, which is
-to not worry so much about individual allocations, but rather about
-overall performance and lifetime groups. Instead, foo_t generally
-should not have a `pool' field. Just allocate as many foo objects as
-you need in the current pool — when that pool gets
-cleared or destroyed, they will all go away simultaneously.</p>
-
-<p>See also the <a href="#exception-handling">Exception handling</a>
-section, for details of how resources associated with a pool are
-cleaned up when that pool is destroyed.</p>
-
-<p>In summary:</p>
-
-<ul>
-
-<li><p>Objects should not have their own pools. An object is
- allocated into a pool defined by the constructor's caller. The
- caller knows the lifetime of the object and will manage it via
- the pool.</p>
-</li>
-
-<li><p>Functions should not create/destroy pools for their operation;
- they should use a pool provided by the caller. Again, the
- caller knows more about how the function will be used, how
- often, how many times, etc. thus, it should be in charge of the
- function's memory usage.</p>
-
- <p>For example, the caller might know that the app will exit upon
- the function's return. Thus, the function would create extra
- work if it built/destroyed a pool. Instead, it should use the
- passed-in pool, which the caller is going to be tossing as part
- of app-exit anyway.</p>
-</li>
-
-<li><p>Whenever an unbounded iteration occurs, an iteration subpool
- should be used.</p>
-</li>
-
-<li><p>Given all of the above, it is pretty well mandatory to pass a
- pool to every function. Since objects are not recording pools
- for themselves, and the caller is always supposed to be
- managing memory, then each function needs a pool, rather than
- relying on some hidden magic pool. In limited cases, objects
- may record the pool used for their construction so that they
- can construct sub-parts, but these cases should be examined
- carefully.</p>
-</li>
-</ul>
-
-
-<p>See also <a href="#tracing-memory-leaks">Tracking down memory
-leaks</a> for tips on diagnosing pool usage problems.</p>
-
-</div> <!-- apr-pools -->
-
-
-<div class="h2" id="apr-status-codes">
-<h2>APR status codes
- <a class="sectionlink" href="#apr-status-codes"
- title="Link to this section">¶</a>
-</h2>
-
-<p>Always check for APR status codes (except APR_SUCCESS) with the
-APR_STATUS_IS_...() macros, not by direct comparison. This is required
-for portability to non-Unix platforms.</p>
-
-</div> <!-- apr-status-codes -->
-
-
-<div class="h2" id="exception-handling">
-<h2>Exception handling
- <a class="sectionlink" href="#exception-handling"
- title="Link to this section">¶</a>
-</h2>
-
-<p>OK, here's how to use exceptions in Subversion.</p>
-
-<ol>
-
-<li><p>Exceptions are stored in svn_error_t structures:</p>
-
-<pre>
-typedef struct svn_error_t
-{
- apr_status_t apr_err; /* APR error value, possibly SVN_ custom err */
- const char *message; /* details from producer of error */
- struct svn_error_t *child; /* ptr to the error we "wrap" */
- apr_pool_t *pool; /* place to generate message strings from */
- const char *file; /* Only used iff SVN_DEBUG */
- long line; /* Only used iff SVN_DEBUG */
-} svn_error_t;
-</pre>
-
-</li>
-
-<li><p>If you are the <em>original</em> creator of an error, you would do
- something like this:</p>
-
- <pre>
-return svn_error_create(SVN_ERR_FOO, NULL,
- "User not permitted to write file");
- </pre>
-
- <p>NOTICE the NULL field... indicating that this error has no
- child, i.e. it is the bottom-most error.</p>
-
- <p>See also the <a href="#error-messages"> section on writing
- error messages</a>.</p>
-
- <p>Subversion internally uses UTF-8 to store its data. This also
- applies to the 'message' string. APR is assumed to return its data
- in the current locale, so any text returned by APR needs
- conversion to UTF-8 before inclusion in the message string.</p>
-</li>
-
-<li><p>If you <em>receive</em> an error, you have three choices:</p>
-
- <ol>
- <li><p>Handle the error yourself. Use either your own code, or
- just call the primitive svn_handle_error(err). (This
- routine unwinds the error stack and prints out messages
- converting them from UTF-8 to the current locale.)</p>
-
- <p>When your routine receives an error which it intends to
- ignore or handle itself, be sure to clean it up using
- svn_error_clear(). Any time such an error is not cleared
- constitutes a <em>memory leak</em>.</p>
- </li>
-
- <li><p>Throw the error upwards, unmodified:</p>
-
- <pre>
- error = some_routine(foo);
- if (error)
- return svn_error_return(error);
- </pre>
-
- <p>Actually, a better way to do this would be with the
- SVN_ERR() macro, which does the same thing:</p>
- <pre>
- SVN_ERR(some_routine(foo));
- </pre>
- </li>
-
- <li><p>Throw the error upwards, wrapping it in a new error
- structure by including it as the "child" argument:</p>
-
- <pre>
- error = some_routine(foo);
- if (error)
- {
- svn_error_t *wrapper = svn_error_create(SVN_ERR_FOO, error,
- "Authorization failed");
- return wrapper;
- }
- </pre>
-
- <p>Of course, there's a convenience routine which creates a
- wrapper error with the same fields as the child, except for
- your custom message:</p>
-
- <pre>
- error = some_routine(foo);
- if (error)
- {
- return svn_error_quick_wrap(error,
- "Authorization failed");
- }
- </pre>
-
- <p>The same can (and should) be done by using the SVN_ERR_W()
- macro:</p>
-
- <pre>
- SVN_ERR_W(some_routine(foo), "Authorization failed");
- </pre>
- </li>
- </ol>
-
- <p>In cases (b) and (c) it is important to know that resources
- allocated by your routine which are associated with a pool, are
- automatically cleaned up when the pool is destroyed. This means
- that there is no need to cleanup these resources before passing
- the error. There is therefore no reason not to use the SVN_ERR()
- and SVN_ERR_W() macros. Resources associated with pools are:</p>
-
- <ul>
-
- <li><p>Memory</p></li>
-
- <li><p>Files</p>
-
- <p>All files opened with apr_file_open are closed at pool
- cleanup. Subversion uses this function in its svn_io_file_*
- api, which means that files opened with svn_io_file_* or
- apr_file_open will be closed at pool cleanup.</p>
-
- <p>Some files (lock files for example) need to be removed when
- an operation is finished. APR has the APR_DELONCLOSE flag for
- this purpose. The following functions create files which are
- removed on pool cleanup:</p>
-
- <ul>
- <li><p>apr_file_open and svn_io_file_open (when passed the
- APR_DELONCLOSE flag)</p></li>
- <li><p>svn_io_open_unique_file (when passed TRUE in its
- delete_on_close)</p></li>
- </ul>
-
- <p>Locked files are unlocked if they were locked using
- svn_io_file_lock.</p>
- </li>
- </ul>
-</li>
-
-<li><p>The <code>SVN_ERR()</code> macro will create a wrapped error when
- <code>SVN_ERR__TRACING</code> is defined. This helps developers
- determine what caused the error, and can be enabled with the
- <code>--enable-maintainer-mode</code> option to <code>configure</code>.
- </p>
-</li>
-
-<li><p>Sometimes, you just want to return whatever a called function
- returns, usually at the end of your own function. Avoid the
- temptation to directly return the result:</p>
- <pre>
- /* Don't do this! */
- return some_routine(foo);</pre>
-
- <p>Instead, use the svn_error_return meta-function to return the value.
- This ensures that stack tracing happens correctly when enabled.</p>
- <pre>
- return svn_error_return(some_routine(foo));</pre>
-
-</li>
-</ol>
-
-</div> <!-- exception-handling -->
-
-
-<div class="h2" id="secure-coding">
-<h2>Secure coding guidelines
- <a class="sectionlink" href="#secure-coding"
- title="Link to this section">¶</a>
-</h2>
-
-<p>Just like almost any other programming language, C has undesirable
-features which enables an attacker to make your program fail in
-predictable ways, often to the attacker's benefit. The goal of these
-guidelines is to make you aware of the pitfalls of C as they apply to
-the Subversion project. You are encouraged to keep these pitfalls in
-mind when reviewing code of your peers, as even the most skilled and
-paranoid programmers make occasional mistakes.</p>
-
-<p>Input validation is the act of defining legal input and rejecting
-everything else. The code must perform input validation on all
-untrusted input. </p>
-
-<p>Security boundaries:</p>
-
-<p>A security boundary in the Subversion server code must be
-identified as such as this enables auditors to quickly determine the
-quality of the boundary. Security boundaries exist where the running
-code has access to information the user does not or where the code
-runs with privileges above those of the user making the
-request. Typical examples of such is code that does access control or
-an application with the SUID bit set.</p>
-
-<p>Functions which make calls to a security boundary must include
-validation checks of the arguments passed. Functions which themselves
-are security boundaries should audit the input received and alarm when
-invoked with improper values. </p>
-
-<p>[### todo: need some examples from Subversion here...]</p>
-
-<p>String operations:</p>
-
-<p>Use the string functions provided in apr_strings.h instead of
-standard C library functions that write to strings. The APR functions
-are safer because they do bounds-checking and dest allocation
-automatically. Although there may be circumstances where it's
-theoretically safe to use plain C string functions (such as when you
-already know the lengths of the source and dest), please use the APR
-functions anyway, so the code is less brittle and more reviewable.</p>
-
-<p>Password storage:</p>
-
-<p>Help users keep their passwords secret: When the client reads or
-writes password locally, it should ensure that the file is mode
-0600. If the file is readable by other users, the client should exit
-with a message that tells the user to change the filemode due to the
-risk of exposure.</p>
-
-</div> <!-- secure-coding -->
-
-
-<div class="h2" id="destruction-of-stacked-resources">
-<h2>Destruction of stacked resources
- <a class="sectionlink" href="#destruction-of-stacked-resources"
- title="Link to this section">¶</a>
-</h2>
-
-<p>Some resources need destruction to ensure correct functioning of the
-application. Such resources include files, especially since open
-files cannot be deleted on Windows.</p>
-
-<p>When writing an API which creates and returns a stream, in the
-background this stream may be stacked on a file or other stream. To
-ensure correct destruction of the resources the stream is built upon,
-it must correctly call the destructors of the stream(s) it is built
-upon (owns).</p>
-
-<p>At first in <a href="http://svn.haxx.se/dev/archive-2005-12/0487.shtml">
-http://svn.haxx.se/dev/archive-2005-12/0487.shtml</a>
-and later in <a href="http://svn.haxx.se/dev/archive-2005-12/0633.shtml">
-http://svn.haxx.se/dev/archive-2005-12/0633.shtml</a> this
-was discussed in more general terms for files, streams, editors and
-window handlers.</p>
-
-<p>As Greg Hudson put it:</p>
-
-<blockquote>
-<p>On consideration, here is where I would like us to be:</p>
-
-<ul><li>Streams which read from or write to an underlying object own that
-object, i.e. closing the stream closes the underlying object, if
-applicable.</li>
-
-<li>The layer (function or data type) which created a stream is
-responsible for closing it, except when the above rule applies.</li>
-
-<li>Window handlers are thought of as an odd kind of stream, and passing
-the final NULL window is considered closing the stream.</li>
-</ul>
-
-<p>If you think of apply_textdelta as creating a window handler, then I
-don't think we're too far off. svn_stream_from_aprfile isn't owning its
-subsidiary file, svn_txdelta_apply is erroneously taking responsibility
-for closing the window stream it is passed, and there may be some other
-deviations.</p>
-</blockquote>
-
-<p>There is one exception to the rules above though. When a stream is passed
-to a function as an argument (for example: the 'out' parameter of
-svn_client_cat2()), that routine can't call the streams destructor, since
-it did not create that resource.</p>
-
-<p>If svn_client_cat2() creates a stream, it must also call the destructor
-for that stream. By the above model, that stream will call the destructor
-for the 'out' parameter. This is however wrong, because the responsibility
-to destruct the 'out' parameter lies elsewhere.</p>
-
-<p>To solve this problem, at least in the stream case, svn_stream_disown()
-has been introduced. This function wraps a stream, making sure it's
-<em>not</em> destroyed, even though any streams stacked upon it may try
-to do so.</p>
-
-</div> <!-- destruction-of-stacked-resources -->
-
-
-<div class="h2" id="other-conventions">
-<h2>Other coding conventions
- <a class="sectionlink" href="#other-conventions"
- title="Link to this section">¶</a>
-</h2>
-
-<p>In addition to the GNU standards, Subversion uses these
-conventions:</p>
-
-<ul>
-<li><p>When using a path or file name as input to most <a
- href="http://svn.collab.net/svn-doxygen/">Subversion APIs</a>, be
- sure to convert them to Subversion's internal/canonical form
- using the <a href="http://svn.collab.net/svn-doxygen/svn__path_8h.html#a0"
- ><tt>svn_path_internal_style()</tt></a> API. Alternately, when
- receiving a path or file name as output from a Subversion API,
- convert them into the expected form for your platform using the
- <a href="http://svn.collab.net/svn-doxygen/svn__path_8h.html#a1"
- ><tt>svn_path_local_style()</tt></a> API.</p></li>
-
-<li><p>Use only spaces for indenting code, never tabs. Tab display
- width is not standardized enough, and anyway it's easier to
- manually adjust indentation that uses spaces.</p>
-</li>
-
-<li><p>Restrict lines to 79 columns, so that code will display well in a
- minimal standard display window. (There can be exceptions, such
- as when declaring a block of 80-column text with a few extra
- columns taken up by indentation, quotes, etc., if splitting each
- line in two would be unreasonably messy.)</p>
-</li>
-
-<li><p>All published functions, variables, and structures must be signified
- with the corresponding library name - such as libsvn_wc's
- svn_wc_adm_open. All library-internal declarations made in a
- library-private header file (such as libsvn_wc/wc.h) must be signified
- by two underscores after the library prefix (such as
- svn_wc__ensure_directory). All declarations private to a single file
- (such as the static function get_entry_url inside of
- <tt>libsvn_wc/update_editor.c</tt>) do not require any
- additional namespace decorations. Symbols that need to be used
- outside a library, but still are not public are put in a shared
- header file in the <tt>include/private/</tt> directory, and use
- the double underscore notation. Such symbols may be used by
- Subversion core code only.</p>
-
- <p>To recap:</p>
- <pre>
- /* Part of published API: subversion/include/svn_wc.h */
- svn_wc_adm_open()
- #define SVN_WC_ADM_DIR_NAME ...
- typedef enum svn_wc_schedule_t ...
-
- /* For use within one library only: subversion/libsvn_wc/wc.h */
- svn_wc__ensure_directory()
- #define SVN_WC__BASE_EXT ...
- typedef struct svn_wc__compat_notify_baton_t ...
-
- /* For use within one file: subversion/libsvn_wc/update_editor.c */
- get_entry_url()
- struct handler_baton {
-
- /* For internal use in svn core code only:
- subversion/include/private/svn_wc_private.h */
- svn_wc__entry_versioned()
- </pre>
-
- <p>Pre-Subversion 1.5, private symbols which needed to be used
- outside of a library were put into public header files,
- using the double underscore notation. This practice has been
- abandoned, and any such symbols are legacy, maintained for <a
- href="#release-numbering">backwards compatibility</a>.</p>
-</li>
-
-<li><p>In text strings that might be printed out (or otherwise made
- available) to users, use only forward quotes around paths and
- other quotable things. For example:</p>
- <pre>
- $ svn revert foo
- svn: warning: svn_wc_is_wc_root: 'foo' is not a versioned resource
- $
- </pre>
-
- <p>There used to be a lot of strings that used a backtick for
- the first quote (`foo' instead of 'foo'), but that looked bad in
- some fonts, and also messed up some people's auto-highlighting,
- so we settled on the convention of always using forward
- quotes.</p>
-</li>
-
-<li><p>If you use Emacs, put something like this in your .emacs file,
- so you get svn-dev.el and svnbook.el when needed:</p>
- <pre>
- ;;; Begin Subversion development section
- (defun my-find-file-hook ()
- (let ((svn-tree-path (expand-file-name "~/projects/subversion"))
- (book-tree-path (expand-file-name "~/projects/svnbook")))
- (cond
- ((string-match svn-tree-path buffer-file-name)
- (load (concat svn-tree-path "/tools/dev/svn-dev")))
- ((string-match book-tree-path buffer-file-name)
- ;; Handle load exception for svnbook.el, because it tries to
- ;; load psgml, and not everyone has that available.
- (condition-case nil
- (load (concat book-tree-path "/src/tools/svnbook"))
- (error
- (message "(Ignored problem loading svnbook.el.)")))))))
-
- (add-hook 'find-file-hooks 'my-find-file-hook)
- ;;; End Subversion development section
- </pre>
-
- <p>You'll need to customize the path for your setup, of course.
- You can also make the regexp to string-match more selective; for
- example, one developer says:</p>
- <pre>
- > Here's the regexp I'm using:
- >
- > "src/svn/[^/]*/\\(subversion\\|tools\\|build\\)/"
- >
- > Two things to notice there: (1) I sometimes have several
- > working copies checked out under ...src/svn, and I want the
- > regexp to match all of them; (2) I want the hook to catch only
- > in "our" directories within the working copy, so I match
- > "subversion", "tools" and "build" explicitly; I don't want to
- > use GNU style in the APR that's checked out into my repo. :-)
- </pre>
-</li>
-
-<li><p>We have a tradition of not marking files with the names of
- individual authors (i.e., we don't put lines like
- "Author: foo" or "@author foo" in a special position
- at the top of a source file). This is to discourage
- territoriality — even when a file has only one
- author, we want to make sure others feel free to make changes.
- People might be unnecessarily hesitant if someone appears to
- have staked a personal claim to the file.</p>
-</li>
-
-<li><p>Put two spaces between the end of one sentence and the start of
- the next. This helps readability, and allows people to use
- their editors' sentence-motion and -manipulation commands.</p>
-</li>
-
-<li><p>There are many other unspoken conventions maintained throughout
- the code, that are only noticed when someone unintentionally
- fails to follow them. Just try to have a sensitive eye for the
- way things are done, and when in doubt, ask.</p>
-</li>
-</ul>
-
-</div> <!-- other-conventions -->
-
-
-<div class="h2" id="log-messages">
-<h2>Writing log messages
- <a class="sectionlink" href="#log-messages"
- title="Link to this section">¶</a>
-</h2>
-
-<p>Every commit needs a log message. </p>
-
-<p>The intended audience for a log message is a developer who is
-already familiar with Subversion, but not necessarily familiar with
-this particular commit. Usually when someone goes back and reads a
-change, he no longer has in his head all the context around that
-change. This is true even if he is the author of the change! All the
-discussions and mailing list threads and everything else may be
-forgotten; the only clue to what the change is about comes from the
-log message and the diff itself. People revisit changes with
-surprising frequency, too: for example, it might be months after the
-original commit and now the change is being ported to a maintenance
-branch.</p>
-
-<p>The log message is the introduction to the change. Start it off
-with one line indicating the general nature of the change, and follow
-that with a descriptive paragraph if necessary. This not only helps
-put developers in the right frame of mind for reading the rest of the
-log message, but also plays well with the "CIA" bot that echoes the
-first line of each commit to realtime forums like IRC. (For details,
-see <a href="http://cia.vc/">http://cia.vc/</a>.) However, if the
-commit is just one simple change to one file, then you can dispense
-with the general description and simply go straight to the detailed
-description, in the standard filename-then-symbol format shown
-below.</p>
-
-<p>Throughout the log message, use full sentences, not sentence
-fragments. Fragments are more often ambiguous, and it takes only a
-few more seconds to write out what you mean. Certain fragments like
-"Doc fix", "New file", or "New function" are acceptable because they
-are standard idioms, and all further details should appear in the
-source code.</p>
-
-<p>The log message should name every affected function, variable,
-macro, makefile target, grammar rule, etc, including the names of
-symbols that are being removed in this commit. This helps people
-searching through the logs later. Don't hide names in wildcards,
-because the globbed portion may be what someone searches for later.
-For example, this is bad:</p>
-
-<pre>
- * subversion/libsvn_ra_pigeons/twirl.c
- (twirling_baton_*): Removed these obsolete structures.
- (handle_parser_warning): Pass data directly to callees, instead
- of storing in twirling_baton_*.
-
- * subversion/libsvn_ra_pigeons/twirl.h: Fix indentation.
-</pre>
-
-<p>Later on, when someone is trying to figure out what happened to
-`twirling_baton_fast', they may not find it if they just search for
-"_fast". A better entry would be:</p>
-
-<pre>
- * subversion/libsvn_ra_pigeons/twirl.c
- (twirling_baton_fast, twirling_baton_slow): Removed these
- obsolete structures.
- (handle_parser_warning): Pass data directly to callees, instead
- of storing in twirling_baton_*.
-
- * subversion/libsvn_ra_pigeons/twirl.h: Fix indentation.
-</pre>
-
-<p>The wildcard is okay in the description for
-`handle_parser_warning', but only because the two structures were
-mentioned by full name elsewhere in the log entry.</p>
-
-<p>You should also include property changes in your log messages.
-For example, if you were to modify the "svn:ignore" property on
-the trunk, you might put something like this in your log:</p>
-
-<pre>
- * trunk/ (svn:ignore): Ignore 'build'.
-</pre>
-
-<p>The above only applies to properties you maintain, not those
-maintained by subversion like "svn:mergeinfo".</p>
-
-<p>Note how each file gets its own entry prefixed with an "*", and the
-changes within a file are grouped by symbol, with the symbols listed
-in parentheses followed by a colon, followed by text describing the
-change. Please adhere to this format, even when only one file is
-changed — not only does consistency aid readability,
-it also allows software to colorize log entries automatically.</p>
-
-<p>As an exception to the above, if you make exactly the same change
-in several files, list all the changed files in one entry. For
-example:</p>
-
-<pre>
- * subversion/libsvn_ra_pigeons/twirl.c,
- subversion/libsvn_ra_pigeons/roost.c:
- Include svn_private_config.h.
-</pre>
-
-<p>If all the changed files are deep inside the source tree, you can
-shorten the file name entries by noting the common prefix before the
-change entries:</p>
-
-<pre>
- [in subversion/bindings/swig/birdsong]
-
- * dialects/nightingale.c (get_base_pitch): Allow 3/4-tone
- pitch variation to account for trait variability amongst
- isolated populations Erithacus megarhynchos.
-
- * dialects/gallus_domesticus.c: Remove. Unreliable due to
- extremely low brain-to-body mass ratio.
-</pre>
-
-<p>If your change is related to a specific issue in the issue tracker,
-then include a string like "issue #N" in the log message, but make
-sure you still summarize what the change is about. For example, if a
-patch resolves issue #1729, then the log message might be:</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>Try to put related changes together. For example, if you create
-svn_ra_get_ansible2(), deprecating svn_ra_get_ansible(), then those
-two things should be near each other in the log message:</p>
-
-<pre>
- * subversion/include/svn_ra.h
- (svn_ra_get_ansible2): New prototype, obsoletes svn_ra_get_ansible.
- (svn_ra_get_ansible): Deprecate.
-</pre>
-
-<p>For large changes or change groups, group the log entry into
-paragraphs separated by blank lines. Each paragraph should be a set
-of changes that accomplishes a single goal, and each group should
-start with a sentence or two summarizing the change. Truly
-independent changes should be made in separate commits, of course.</p>
-
-<p>See <a href="#crediting">Crediting</a> for how to give credit to
-someone else if you are committing their patch, or committing a change
-they suggested.</p>
-
-<p>One should never need the log entries to understand the current
-code. If you find yourself writing a significant explanation in the
-log, you should consider carefully whether your text doesn't actually
-belong in a comment, alongside the code it explains. Here's an
-example of doing it right:</p>
-
-<pre>
- (consume_count): If `count' is unreasonable, return 0 and don't
- advance input pointer.
-</pre>
-
-<p>And then, in `consume_count' in `cplus-dem.c':</p>
-
-<pre>
- while (isdigit((unsigned char)**type))
- {
- count *= 10;
- count += **type - '0';
- /* A sanity check. Otherwise a symbol like
- `_Utf390_1__1_9223372036854775807__9223372036854775'
- can cause this function to return a negative value.
- In this case we just consume until the end of the string. */
- if (count > strlen(*type))
- {
- *type = save;
- return 0;
- }
-</pre>
-
-<p>This is why a new function, for example, needs only a log entry
-saying "New Function" --- all the details should be in the source.</p>
-
-<p>You can make common-sense exceptions to the need to name everything
-that was changed. For example, if you have made a change which
-requires trivial changes throughout the rest of the program (e.g.,
-renaming a variable), you needn't name all the functions affected, you
-can just say "All callers changed". When renaming any symbol, please
-remember to mention both the old and new names, for traceability; see
-r861020 for an example.</p>
-
-<p>In general, there is a tension between making entries easy to find
-by searching for identifiers, and wasting time or producing unreadable
-entries by being exhaustive. Use the above guidelines and your best
-judgment, and be considerate of your fellow developers. (Also, use
-"svn log" to see how others have been writing their log entries.)</p>
-
-<p>Log messages for documentation or translation have somewhat looser
-guidelines. The requirement to name every symbol obviously does not
-apply, and if the change is just one more increment in a continuous
-process such as translation, it's not even necessary to name every
-file. Just briefly summarize the change, for example: "More work on
-Malagasy translation." Please write your log messages in English, so
-everybody involved in the project can understand the changes you
-made.</p>
-
-</div> <!-- log-messages -->
-
-
-<div class="h2" id="crediting">
-<h2>Crediting
- <a class="sectionlink" href="#crediting"
- title="Link to this section">¶</a>
-</h2>
-
-<p>It is very important to record code contributions in a consistent
-and parseable way. This allows us to write scripts to figure out who
-has been actively contributing — and what they have
-contributed — so we can <a
-href="http://www.red-bean.com/svnproject/contribulyzer/">spot
-potential new committers quickly</a>. The Subversion project uses
-human-readable but machine-parseable fields in log messages to
-accomplish this.</p>
-
-<p>When committing a patch written by someone else, use
-"Patch by: " at the beginning of a line to indicate the
-author:</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.
-
- Patch by: J. Random <jrandom@example.com>
-</pre>
-
-<p>If multiple individuals wrote the patch, list them each on a
-separate line — making sure to start each continuation
-line with whitespace. Non-committers should be listed by name, if
-known, and e-mail. Full and partial committers should be listed by
-their canonical usernames from <a
-href="http://svn.apache.org/repos/asf/subversion/trunk/COMMITTERS"
->COMMITTERS</a> (the leftmost column in that file). Additionally,
-"me" is an acceptable shorthand for the person actually committing the
-change.</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.
-
- Patch by: J. Random <jrandom@example.com>
- Enrico Caruso <codingtenor@codingtenor.com>
- jcommitter
- me
-</pre>
-
-<p>If someone found the bug or pointed out the problem, but didn't
-write the patch, indicate their contribution with
-"Found by: ":</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.
-
- Found by: J. Random <jrandom@example.com>
-</pre>
-
-<p>If someone suggested something useful, but didn't write the patch,
-indicate their contribution with "Suggested by: ":</p>
-
-<pre>
- Extend the Contribulyzer syntax to distinguish finds from ideas.
-
- * www/hacking.html (crediting): Adjust accordingly.
-
- Suggested by: dlr
-</pre>
-
-<p>If someone reviewed the change, use "Review by: "
-(or "Reviewed by: " if you prefer):</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.
-
- Review by: Eagle Eyes <eeyes@example.com>
-</pre>
-
-<p>A field may have multiple lines, and a log message may contain any
-combination of fields:</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.
-
- Patch by: J. Random <jrandom@example.com>
- Enrico Caruso <codingtenor@codingtenor.com>
- me
- Found by: J. Random <jrandom@example.com>
- Review by: Eagle Eyes <eeyes@example.com>
- jcommitter
-</pre>
-
-<p>Further details about a contribution should be listed in a
-parenthetical aside immediately after the corresponding field. Such
-an aside always applies to the field right above it; in the following
-example, the fields have been spaced out for readability, but note
-that the spacing is optional and not necessary for parseability:</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.
-
- Patch by: J. Random <jrandom@example.com>
- (Tweaked by me.)
-
- Review by: Eagle Eyes <eeyes@example.com>
- jcommitter
- (Eagle Eyes caught an off-by-one-error in the basename extraction.)
-</pre>
-
-<p>Currently, these fields</p>
-
-<pre>
- Patch by:
- Suggested by:
- Found by:
- Review by:
-</pre>
-
[... 2708 lines stripped ...]