subversion-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jerenkra...@apache.org
Subject svn commit: r906405 [1/3] - /subversion/site/publish/docs/community-guide/
Date Thu, 04 Feb 2010 08:56:05 GMT
Author: jerenkrantz
Date: Thu Feb  4 08:56:04 2010
New Revision: 906405

URL: http://svn.apache.org/viewvc?rev=906405&view=rev
Log:
* docs/community-guide/*: Take a shot at refactoring community guide into
  sub-pages while also retaining single-page view for those who like Ctrl+F.

(This is not linked up to as part of the site, so it's "hidden" for now.)

Added:
    subversion/site/publish/docs/community-guide/building.html   (with props)
    subversion/site/publish/docs/community-guide/building.part.html   (with props)
    subversion/site/publish/docs/community-guide/building.toc.html   (with props)
    subversion/site/publish/docs/community-guide/conventions.html   (with props)
    subversion/site/publish/docs/community-guide/conventions.part.html   (with props)
    subversion/site/publish/docs/community-guide/conventions.toc.html   (with props)
    subversion/site/publish/docs/community-guide/debugging.html   (with props)
    subversion/site/publish/docs/community-guide/debugging.part.html   (with props)
    subversion/site/publish/docs/community-guide/debugging.toc.html   (with props)
    subversion/site/publish/docs/community-guide/general.html   (with props)
    subversion/site/publish/docs/community-guide/general.part.html   (with props)
    subversion/site/publish/docs/community-guide/general.toc.html   (with props)
    subversion/site/publish/docs/community-guide/guide-nav.html   (with props)
    subversion/site/publish/docs/community-guide/guide.css   (with props)
    subversion/site/publish/docs/community-guide/index-onepage.html   (with props)
    subversion/site/publish/docs/community-guide/issues.html   (with props)
    subversion/site/publish/docs/community-guide/issues.part.html   (with props)
    subversion/site/publish/docs/community-guide/issues.toc.html   (with props)
    subversion/site/publish/docs/community-guide/l10n.html   (with props)
    subversion/site/publish/docs/community-guide/l10n.part.html   (with props)
    subversion/site/publish/docs/community-guide/l10n.toc.html   (with props)
    subversion/site/publish/docs/community-guide/mailing-lists.html   (with props)
    subversion/site/publish/docs/community-guide/mailing-lists.part.html   (with props)
    subversion/site/publish/docs/community-guide/mailing-lists.toc.html   (with props)
    subversion/site/publish/docs/community-guide/releasing.html   (with props)
    subversion/site/publish/docs/community-guide/releasing.part.html   (with props)
    subversion/site/publish/docs/community-guide/releasing.toc.html   (with props)
    subversion/site/publish/docs/community-guide/roles.html   (with props)
    subversion/site/publish/docs/community-guide/roles.part.html   (with props)
    subversion/site/publish/docs/community-guide/roles.toc.html   (with props)

Added: subversion/site/publish/docs/community-guide/building.html
URL: http://svn.apache.org/viewvc/subversion/site/publish/docs/community-guide/building.html?rev=906405&view=auto
==============================================================================
--- subversion/site/publish/docs/community-guide/building.html (added)
+++ subversion/site/publish/docs/community-guide/building.html Thu Feb  4 08:56:04 2010
@@ -0,0 +1,21 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" 
+   "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Apache Subversion - Community Guide - Building and Testing</title>
+<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
+<style type="text/css">
+  @import url("/style/site.css");
+  @import url("/docs/community-guide/guide.css");
+</style>
+</head>
+
+<body>
+<!--#include virtual="/site-banner.html" -->
+<!--#include virtual="/docs/community-guide/guide-nav.html" -->
+<div id="site-content">
+<!--#include virtual="/site-notice.html" -->
+
+<!--#include virtual="/docs/community-guide/building.part.html"-->
+</body>
+</html>

Propchange: subversion/site/publish/docs/community-guide/building.html
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: subversion/site/publish/docs/community-guide/building.html
------------------------------------------------------------------------------
    svn:executable = *

Propchange: subversion/site/publish/docs/community-guide/building.html
------------------------------------------------------------------------------
    svn:mime-type = text/html

Added: subversion/site/publish/docs/community-guide/building.part.html
URL: http://svn.apache.org/viewvc/subversion/site/publish/docs/community-guide/building.part.html?rev=906405&view=auto
==============================================================================
--- subversion/site/publish/docs/community-guide/building.part.html (added)
+++ subversion/site/publish/docs/community-guide/building.part.html Thu Feb  4 08:56:04 2010
@@ -0,0 +1,316 @@
+<div class="h1" id="building-and-testing" title="building-and-testing">
+<h1>Building and Testing</h1>
+
+<div class="h2" id="configury" title="configury">
+<h2>The configuration/build system under unix</h2>
+
+<p>Greg Stein wrote a custom build system for Subversion, which had
+been using `automake' and recursive Makefiles.  Now it uses a single,
+top-level Makefile, generated from Makefile.in (which is kept under
+revision control).  `Makefile.in' in turn includes `build-outputs.mk',
+which is automatically generated from `build.conf' by the
+`gen-make.py' script.  Thus, the latter two are under revision
+control, but `build-outputs.mk' is not.</p>
+
+<p>Here is Greg's original mail describing the system, followed by
+some advice about hacking it:</p>
+
+<pre>
+   From: Greg Stein &lt;gstein@lyra.org&gt;
+   Subject:  new build system (was: Re: CVS update: MODIFIED: ac-helpers ...)
+   To: dev@subversion.tigris.org
+   Date: Thu, 24 May 2001 07:20:55 -0700
+   Message-ID: &lt;20010524072055.F5402@lyra.org&gt;
+
+   On Thu, May 24, 2001 at 01:40:17PM -0000, gstein@tigris.org wrote:
+   &gt;   User: gstein
+   &gt;   Date: 01/05/24 06:40:17
+   &gt;
+   &gt;   Modified:    ac-helpers .cvsignore svn-apache.m4
+   &gt;   Added:       .        Makefile.in
+   &gt;   Log:
+   &gt;   Switch over to the new non-recursive build system.
+   &gt;...
+
+   Okay... this is it. We're now on the build system.
+
+       "It works on my machine."
+
+   I suspect there may be some tweaks to make on different OSs. I'd be
+   interested to hear if Ben can really build with normal BSD make. It
+   should be possible.
+
+   The code supports building, installation, checking, and
+   dependencies. It does *NOT* yet deal with the doc/ subdirectory. That
+   is next; I figured this could be rolled out and get the kinks worked
+   out while I do the doc/ stuff.  Oh, it doesn't build Neon or APR yet
+   either. I also saw a problem where libsvn_fs wasn't getting built
+   before linking one of the test proggies (see below).
+
+   Basic operation: same as before.
+
+   $ ./autogen.sh
+   $ ./configure OPTIONS
+   $ make
+   $ make check
+   $ make install
+
+   There are some "make check" scripts that need to be fixed up. That'll
+   happen RSN. Some of them create their own log, rather than spewing to
+   stdout (where the top-level make will place the output into
+   [TOP]/tests.log).
+
+   The old Makefile.am files are still around, but I'll be tossing those
+   along with a bunch of tweaks to all the .cvsignore files. There are a
+   few other cleanups, too. But that can happen as a step two.
+
+   [ $ cvs rm -f `find . -name Makefile.rm`
+
+     See the mistake in that line? I didn't when I typed it. The find
+     returned nothing, so cvs rm -f proceeded to delete my entire
+     tree. And the -f made sure to delete all my source files, too. Good
+     fugging thing that I had my mods in some Emacs buffers, or I'd be
+     bitching.
+
+     I am *so* glad that Ben coded SVN to *not* delete locally modified
+     files *and* that we have an "undel" command. I had to go and tweak a
+     bazillion Entries files to undo the delete...
+   ]
+
+   The top-level make has a number of shortcuts in it (well, actually in
+   build-outputs.mk):
+
+   $ make subversion/libsvn_fs/libsvn_fs.la
+
+   or
+
+   $ make libsvn_fs
+
+   The two are the same. So... when your test proggie fails to link
+   because libsvn_fs isn't around, just run "make libsvn_fs" to build it
+   immediately, then go back to the regular "make".
+
+   Note that the system still conditionally builds the FS stuff based
+   on whether DB (See 'Building on Unix' below) is available, and
+   mod_dav_svn if Apache is available.
+
+   Handy hint: if you don't like dependencies, then you can do:
+
+   $ ./autogen.sh -s
+
+   That will skip the dependency generation that goes into
+   build-outputs.mk. It makes the script run quite a bit faster (48 secs
+   vs 2 secs on my poor little Pentium 120).
+
+   Note that if you change build.conf, you can simply run:
+
+   $ ./gen-make.py build.conf
+
+   to regen build-outputs.mk. You don't have to go back through the whole
+   autogen.sh / configure process.
+
+   You should also note that autogen.sh and configure run much faster now
+   that we don't have the automake crap. Oh, and our makefiles never
+   re-run configure on you out of the blue (gawd, I hated when automake
+   did that to me).
+
+   Obviously, there are going to be some tweaky things going on. I also
+   think that the "shadow" builds or whatever they're called (different
+   source and build dirs) are totally broken. Something tweaky will have
+   to happen there.  But, thankfully, we only have one Makefile to deal
+   with.
+
+   Note that I arrange things so that we have one generated file
+   (build-outputs.mk), and one autoconf-generated file (Makefile from
+   .in).  I also tried to shove as much logic/rules into
+   Makefile.in. Keeping build-outputs.mk devoid of rules (thus, implying
+   gen-make.py devoid of rules in its output generation) manes that
+   tweaking rules in Makefile.in is much more approachable to people.
+
+   I think that is about it. Send problems to the dev@ list and/or feel
+   free to dig in and fix them yourself. My next steps are mostly
+   cleanup. After that, I'm going to toss out our use of libtool and rely
+   on APR's libtool setup (no need for us to replicate what APR already
+   did).
+
+   Cheers,
+   -g
+
+   --
+   Greg Stein, http://www.lyra.org/
+</pre>
+
+<p>And here is some advice for those changing or testing the
+configuration/build system:</p>
+
+<pre>
+   From: Karl Fogel &lt;kfogel@collab.net&gt;
+   To: dev@subversion.tigris.org
+   Subject: when changing build/config stuff, always do this first
+   Date: Wed 28 Nov 2001
+
+   Yo everyone: if you change part of the configuration/build system,
+   please make sure to clean out any old installed Subversion libs
+   *before* you try building with your changes.  If you don't do this,
+   your changes may appear to work fine, when in fact they would fail if
+   run on a truly pristine system.
+
+   This script demonstrates what I mean by "clean out".  This is
+   `/usr/local/cleanup.sh' on my system.  It cleans out the Subversion
+   libs (and the installed httpd-2.0 libs, since I'm often reinstalling
+   that too):
+
+      #!/bin/sh
+
+      # Take care of libs
+      cd /usr/local/lib
+      rm -f APRVARS
+      rm -f libapr*
+      rm -f libexpat*
+      rm -f libneon*
+      rm -f libsvn*
+
+      # Take care of headers
+      cd /usr/local/include
+      rm -f apr*
+      rm -f svn*
+      rm -f neon/*
+
+      # Take care of headers
+      cd /usr/local/apache2/lib
+      rm -f *
+
+   When someone reports a configuration bug and you're trying to
+   reproduce it, run this first. :-)
+
+   The voice of experience,
+   -Karl
+</pre>
+
+<p>The build system is a vital tool for all developers working on trunk.
+Sometimes, changes made to the build system work perfectly fine for
+one developer, but inadvertently break the build system for another.</p>
+
+<p>
+To prevent loss of productivity, any committer (full or partial) can
+immediately revert any build system change that breaks their ability to
+effectively do development on their platform of choice, as a matter of
+ordinary routing, without fear of accusations of an over-reaction.
+The log message of the commit reverting the change should contain an
+explanatory note saying why the change is being reverted, containing
+sufficient detail to be suitable to start off a discussion of the
+problem on dev@, should someone chose to reply to the commit mail.</p>
+
+<p>However, care should be taken not go into &quot;default revert mode&quot;.
+If you can quickly fix the problem, then please do so. If not, then stop and
+think about it for a minute. After you've thought about it, and you still have
+no solution, go ahead and revert the change, and bring the discussion to the
+list.</p>
+
+<p>Once the change has been reverted, it is up to the original committer of
+the reverted change to either recommit a fixed version of their original
+change, if, based on the reverting committer's rationale, they feel very
+certain that their new version definitely is fixed, or, to submit the
+revised version for testing to the reverting committer before committing
+it again.</p>
+
+</div> <!-- configury -->
+
+
+<div class="h2" id="automated-tests" title="automated-tests">
+<h2>Automated tests</h2>
+
+<p>For a description of how to use and add tests to Subversion's
+automated test framework, please read <a
+href="http://svn.apache.org/repos/asf/subversion/trunk/subversion/tests/README"
+>subversion/tests/README</a> and <a
+href="http://svn.apache.org/repos/asf/subversion/trunk/subversion/tests/cmdline/README"
+>subversion/tests/cmdline/README</a>.</p>
+
+<p>Various people have arranged for the automated test framework to
+run at regular intervals on their own machines, sending the results to
+the svn-breakage@subversion.tigris.org mailing list.  The more
+different platforms the tests run on, the more quickly we can detect
+portability bugs in Subversion.  If you'd like to send svn-breakage
+messages too, use the <a
+href="http://svn.apache.org/repos/asf/subversion/trunk/tools/test-scripts/svntest/" 
+>svntest</a> framework (start at the <a
+href="http://svn.apache.org/repos/asf/subversion/trunk/tools/test-scripts/svntest/README" 
+>README</a>).</p>
+
+</div> <!-- automated-tests -->
+
+
+<div class="h2" id="build-farm" title="build-farm">
+<h2>Build farm</h2>
+
+<p>Lieven Govaerts has set up a
+<a href="http://buildbot.sourceforge.net/" >BuildBot</a> build/test
+farm at <a href="http://buildbot.subversion.org/buildbot/"
+>http://buildbot.subversion.org/buildbot/</a>, see this message:</p>
+
+<pre>
+   <a href="http://subversion.tigris.org/servlets/ReadMsg?list=dev&amp;msgNo=114212">http://subversion.tigris.org/servlets/ReadMsg?list=dev&amp;msgNo=114212</a>
+   (Thread URL: <a href="http://subversion.tigris.org/servlets/BrowseList?list=dev&amp;by=thread&amp;from=450110">http://subversion.tigris.org/servlets/BrowseList?list=dev&amp;by=thread&amp;from=450110</a>)
+   Message-ID: 20060326205918.F3C50708B0@adicia.telenet-ops.be
+   From: "Lieven Govaerts" &lt;lgo@mobsol.be&gt;
+   To: &lt;dev@subversion.tigris.org&gt;
+   Subject: Update: Subversion build and test farm with Buildbot.
+   Date: Sun, 26 Mar 2006 22:56:11 +0200
+</pre>
+
+<p>for more details.  (<a href="http://buildbot.sourceforge.net/"
+>BuildBot</a> is a system for centrally managing multiple automated
+testing environments; it's especially useful for portability testing,
+including of uncommitted changes.)</p>
+
+<p class="todo">Once the details of the build farm get finalized,
+integrate those instructions here.  Perhaps the information at
+<a href="https://svn.apache.org/repos/asf/subversion/trunk/www/build-farm.html?p=867958"
+>https://svn.apache.org/repos/asf/subversion/trunk/www/build-farm.html?p=867958</a>
+can serve as a good starting point?</p>
+
+</div> <!-- build-farm -->
+
+
+<div class="h2" id="write-test-cases-first" title="write-test-cases-first">
+<h2>Writing test cases before code</h2>
+
+<pre>
+From: Karl Fogel &lt;kfogel@collab.net&gt;
+Subject: writing test cases
+To: dev@subversion.tigris.org
+Date: Mon, 5 Mar 2001 15:58:46 -0600
+
+Many of us implementing the filesystem interface have now gotten into
+the habit of writing the test cases (see fs-test.c) *before* writing
+the actual code.  It's really helping us out a lot -- for one thing,
+it forces one to define the task precisely in advance, and also it
+speedily reveals the bugs in one's first try (and second, and
+third...).
+
+I'd like to recommend this practice to everyone.  If you're
+implementing an interface, or adding an entirely new feature, or even
+just fixing a bug, a test for it is a good idea.  And if you're going
+to write the test anyway, you might as well write it first. :-)
+
+Yoshiki Hayashi's been sending test cases with all his patches lately,
+which is what inspired me to write this mail to encourage everyone to
+do the same.  Having those test cases makes patches easier to examine,
+because they show the patch's purpose very clearly.  It's like having
+a second log message, one whose accuracy is verified at run-time.
+
+That said, I don't think we want a rigid policy about this, at least
+not yet.  If you encounter a bug somewhere in the code, but you only
+have time to write a patch with no test case, that's okay -- having
+the patch is still useful; someone else can write the test case.
+
+As Subversion gets more complex, though, the automated test suite gets
+more crucial, so let's all get in the habit of using it early.
+
+-K
+</pre>
+
+</div> <!-- write-test-cases-first -->
+
+</div> <!-- testing -->

Propchange: subversion/site/publish/docs/community-guide/building.part.html
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: subversion/site/publish/docs/community-guide/building.part.html
------------------------------------------------------------------------------
    svn:executable = *

Propchange: subversion/site/publish/docs/community-guide/building.part.html
------------------------------------------------------------------------------
    svn:keywords = Date

Propchange: subversion/site/publish/docs/community-guide/building.part.html
------------------------------------------------------------------------------
    svn:mime-type = text/html

Added: subversion/site/publish/docs/community-guide/building.toc.html
URL: http://svn.apache.org/viewvc/subversion/site/publish/docs/community-guide/building.toc.html?rev=906405&view=auto
==============================================================================
--- subversion/site/publish/docs/community-guide/building.toc.html (added)
+++ subversion/site/publish/docs/community-guide/building.toc.html Thu Feb  4 08:56:04 2010
@@ -0,0 +1,8 @@
+  <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>

Propchange: subversion/site/publish/docs/community-guide/building.toc.html
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: subversion/site/publish/docs/community-guide/building.toc.html
------------------------------------------------------------------------------
    svn:executable = *

Propchange: subversion/site/publish/docs/community-guide/building.toc.html
------------------------------------------------------------------------------
    svn:keywords = Date

Propchange: subversion/site/publish/docs/community-guide/building.toc.html
------------------------------------------------------------------------------
    svn:mime-type = text/html

Added: subversion/site/publish/docs/community-guide/conventions.html
URL: http://svn.apache.org/viewvc/subversion/site/publish/docs/community-guide/conventions.html?rev=906405&view=auto
==============================================================================
--- subversion/site/publish/docs/community-guide/conventions.html (added)
+++ subversion/site/publish/docs/community-guide/conventions.html Thu Feb  4 08:56:04 2010
@@ -0,0 +1,21 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" 
+   "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Apache Subversion - Community Guide - Coding and Commit Conventions</title>
+<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
+<style type="text/css">
+  @import url("/style/site.css");
+  @import url("/docs/community-guide/guide.css");
+</style>
+</head>
+
+<body>
+<!--#include virtual="/site-banner.html" -->
+<!--#include virtual="/docs/community-guide/guide-nav.html" -->
+<div id="site-content">
+<!--#include virtual="/site-notice.html" -->
+
+<!--#include virtual="/docs/community-guide/conventions.part.html"-->
+</body>
+</html>

Propchange: subversion/site/publish/docs/community-guide/conventions.html
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: subversion/site/publish/docs/community-guide/conventions.html
------------------------------------------------------------------------------
    svn:executable = *

Propchange: subversion/site/publish/docs/community-guide/conventions.html
------------------------------------------------------------------------------
    svn:mime-type = text/html

Added: subversion/site/publish/docs/community-guide/conventions.part.html
URL: http://svn.apache.org/viewvc/subversion/site/publish/docs/community-guide/conventions.part.html?rev=906405&view=auto
==============================================================================
--- subversion/site/publish/docs/community-guide/conventions.part.html (added)
+++ subversion/site/publish/docs/community-guide/conventions.part.html Thu Feb  4 08:56:04 2010
@@ -0,0 +1,1158 @@
+<div class="h1" id="conventions" title="conventions">
+<h1>Coding and Commit Conventions</h1>
+
+<div class="h2" id="interface-visibility" title="interface-visibility">
+<h2>Code modularity and interface visibility</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" title="coding-style">
+<h2>Coding style</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 &amp;&amp; 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" title="use-page-breaks">
+<h2>Using page breaks</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" title="error-messages">
+<h2>Error message conventions</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" title="apr-pools">
+<h2>APR pool usage conventions</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 &lt; 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 &lt; n; ++i)
+      {
+        const char *intermediate_result;
+        const char *key, *val;
+        
+        svn_pool_clear(iterpool);
+        SVN_ERR(do_something(&amp;intermediate_result, ..., iterpool));
+        SVN_ERR(get_result(intermediate_result, &amp;key, &amp;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-&gt;field1 = arg1;
+      foo-&gt;field2 = arg2;
+      foo-&gt;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-&gt;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&nbsp;&mdash; 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" title="apr-status-codes">
+<h2>APR status codes</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" title="exception-handling">
+<h2>Exception handling</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" title="secure-coding">
+<h2>Secure coding guidelines</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"
+             title="destruction-of-stacked-resources">
+<h2>Destruction of stacked resources</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" title="other-conventions">
+<h2>Other coding conventions</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>
+      &gt; Here's the regexp I'm using:
+      &gt; 
+      &gt;     "src/svn/[^/]*/\\(subversion\\|tools\\|build\\)/"
+      &gt;
+      &gt; Two things to notice there: (1) I sometimes have several
+      &gt; working copies checked out under ...src/svn, and I want the
+      &gt; regexp to match all of them; (2) I want the hook to catch only
+      &gt; in "our" directories within the working copy, so I match
+      &gt; "subversion", "tools" and "build" explicitly; I don't want to
+      &gt; 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:&nbsp;foo" or "@author&nbsp;foo" in a special position
+      at the top of a source file).  This is to discourage
+      territoriality&nbsp;&mdash; 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" title="log-messages">
+<h2>Writing log messages</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&nbsp;&mdash; 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 &gt; 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" title="crediting">
+<h2>Crediting</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&nbsp;&mdash; and what they have
+contributed&nbsp;&mdash; 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&nbsp;by:&nbsp;" 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 &lt;jrandom@example.com&gt;
+</pre>
+
+<p>If multiple individuals wrote the patch, list them each on a
+separate line&nbsp;&mdash; 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 &lt;jrandom@example.com&gt;
+             Enrico Caruso &lt;codingtenor@codingtenor.com&gt;
+             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&nbsp;by:&nbsp;":</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 &lt;jrandom@example.com&gt;
+</pre>
+
+<p>If someone suggested something useful, but didn't write the patch,
+indicate their contribution with "Suggested&nbsp;by:&nbsp;":</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&nbsp;by:&nbsp;"
+(or "Reviewed&nbsp;by:&nbsp;" 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 &lt;eeyes@example.com&gt;
+</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 &lt;jrandom@example.com&gt;
+             Enrico Caruso &lt;codingtenor@codingtenor.com&gt;
+             me
+   Found by: J. Random &lt;jrandom@example.com&gt;
+   Review by: Eagle Eyes &lt;eeyes@example.com&gt;
+              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 &lt;jrandom@example.com&gt;
+   (Tweaked by me.)
+
+   Review by: Eagle Eyes &lt;eeyes@example.com&gt;
+              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>
+
+<p>are the only officially-supported crediting fields (where
+"supported" means scripts know to look for them), and they are widely
+used in Subversion log messages.  Future fields will probably be of
+the form "VERB&nbsp;by:&nbsp;", and from time to time someone may use
+a field that sounds official but really is not&nbsp;&mdash; for
+example, there are a few instances of "Reported&nbsp;by:&nbsp;".
+These are okay, but try to use an official field, or a parenthetical
+aside, in preference to creating your own.  Also, don't use
+"Reported&nbsp;by:&nbsp;" when the reporter is already recorded in an
+issue; instead, simply refer to the issue.</p>
+
+<p>Look over Subversion's existing log messages to see how to use
+these fields in practice.  This command from the top of your trunk
+working copy will help:</p>
+
+<pre>
+svn log | contrib/client-side/search-svnlog.pl "(Patch|Review|Suggested) by: "
+</pre>
+
+<p><b>Note:</b> The "Approved&nbsp;by:&nbsp;" field seen in some
+commit messages is totally unrelated to these crediting fields, and is
+generally not parsed by scripts.  It is simply the standard syntax for
+indicating either who approved a partial committer's commit outside
+their usual area, or (in the case of merges to release branches) who
+voted for the change to be merged.</p>
+
+</div> <!-- crediting -->
+
+</div> <!-- conventions -->

Propchange: subversion/site/publish/docs/community-guide/conventions.part.html
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: subversion/site/publish/docs/community-guide/conventions.part.html
------------------------------------------------------------------------------
    svn:executable = *

Propchange: subversion/site/publish/docs/community-guide/conventions.part.html
------------------------------------------------------------------------------
    svn:keywords = Date

Propchange: subversion/site/publish/docs/community-guide/conventions.part.html
------------------------------------------------------------------------------
    svn:mime-type = text/html

Added: subversion/site/publish/docs/community-guide/conventions.toc.html
URL: http://svn.apache.org/viewvc/subversion/site/publish/docs/community-guide/conventions.toc.html?rev=906405&view=auto
==============================================================================
--- subversion/site/publish/docs/community-guide/conventions.toc.html (added)
+++ subversion/site/publish/docs/community-guide/conventions.toc.html Thu Feb  4 08:56:04 2010
@@ -0,0 +1,16 @@
+  <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>

Propchange: subversion/site/publish/docs/community-guide/conventions.toc.html
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: subversion/site/publish/docs/community-guide/conventions.toc.html
------------------------------------------------------------------------------
    svn:executable = *

Propchange: subversion/site/publish/docs/community-guide/conventions.toc.html
------------------------------------------------------------------------------
    svn:keywords = Date

Propchange: subversion/site/publish/docs/community-guide/conventions.toc.html
------------------------------------------------------------------------------
    svn:mime-type = text/html

Added: subversion/site/publish/docs/community-guide/debugging.html
URL: http://svn.apache.org/viewvc/subversion/site/publish/docs/community-guide/debugging.html?rev=906405&view=auto
==============================================================================
--- subversion/site/publish/docs/community-guide/debugging.html (added)
+++ subversion/site/publish/docs/community-guide/debugging.html Thu Feb  4 08:56:04 2010
@@ -0,0 +1,21 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" 
+   "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Apache Subversion - Community Guide - Debugging Subversion</title>
+<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
+<style type="text/css">
+  @import url("/style/site.css");
+  @import url("/docs/community-guide/guide.css");
+</style>
+</head>
+
+<body>
+<!--#include virtual="/site-banner.html" -->
+<!--#include virtual="/docs/community-guide/guide-nav.html" -->
+<div id="site-content">
+<!--#include virtual="/site-notice.html" -->
+
+<!--#include virtual="/docs/community-guide/debugging.part.html"-->
+</body>
+</html>

Propchange: subversion/site/publish/docs/community-guide/debugging.html
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: subversion/site/publish/docs/community-guide/debugging.html
------------------------------------------------------------------------------
    svn:executable = *

Propchange: subversion/site/publish/docs/community-guide/debugging.html
------------------------------------------------------------------------------
    svn:mime-type = text/html

Added: subversion/site/publish/docs/community-guide/debugging.part.html
URL: http://svn.apache.org/viewvc/subversion/site/publish/docs/community-guide/debugging.part.html?rev=906405&view=auto
==============================================================================
--- subversion/site/publish/docs/community-guide/debugging.part.html (added)
+++ subversion/site/publish/docs/community-guide/debugging.part.html Thu Feb  4 08:56:04 2010
@@ -0,0 +1,255 @@
+<div class="h1" id="debugging" title="debugging">
+<h1>Debugging Subversion</h1>
+
+<div class="h2" id="server-debugging" title="server-debugging">
+<h2>Debugging the server</h2>
+
+<div class="h3" id="debugging-ra-dav" title="debugging-ra-dav">
+<h3>Debugging the DAV server</h3>
+
+<p>'mod_dav_svn.so' contains the main Subversion server logic; it runs
+as a module within mod_dav, which runs as a module within httpd.
+Since httpd is probably using dynamic shared modules, you normally
+won't be able to set breakpoints in advance when you start Apache in a
+debugger such as GDB.  Instead, you'll need to start up, then
+interrupt httpd, set your breakpoint, and continue:</p>
+
+<pre>
+   % gdb httpd
+   (gdb) run -X
+   ^C
+   (gdb) break some_func_in_mod_dav_svn
+   (gdb) continue
+</pre>
+
+<p>The -X switch is equivalent to -DONE_PROCESS and -DNO_DETACH, which
+ensure that httpd runs as a single thread and remains attached to the
+tty, respectively.  As soon as it starts, it sits and waits for
+requests; that's when you hit control-C and set your breakpoint.</p>
+
+<p>You'll probably want to watch Apache's run-time logs</p>
+
+<pre>
+   /usr/local/apache2/logs/error_log
+   /usr/local/apache2/logs/access_log
+</pre>
+
+<p>to help determine what might be going wrong and where to set
+breakpoints.</p>
+
+</div> <!-- debugging-ra-dav -->
+
+<div class="h3" id="debugging-ra-svn" title="debugging-ra-svn">
+<h3>Debugging the ra_svn client and server, on Unix</h3>
+
+<p>Bugs in ra_svn usually manifest themselves with one of the
+following cryptic error messages:</p>
+
+<pre>
+  svn: Malformed network data
+  svn: Connection closed unexpectedly
+</pre>
+
+<p>(The first message can also mean the data stream was corrupted in
+tunnel mode by user dotfiles or hook scripts; see 
+<a href="http://subversion.tigris.org/issues/show_bug.cgi?id=1145"
+>issue&nbsp;#1145</a>.)  The first message generally means you to have
+to debug the client; the second message generally means you have to
+debug the server.</p>
+
+<p>It is easiest to debug ra_svn using a build with --disable-shared
+--enable-maintainer-mode.  With the latter option, the error message
+will tell you exactly what line to set a breakpoint at; otherwise,
+look up the line number at the end of marshal.c:vparse_tuple() where
+it returns the "Malformed network data" error.</p>
+
+<p>To debug the client, simply pull it up in gdb, set a breakpoint,
+and run the offending command:</p>
+
+<pre>
+  % gdb svn
+  (gdb) break marshal.c:NNN
+  (gdb) run ARGS
+  Breakpoint 1, vparse_tuple (list=___, pool=___, fmt=___, 
+    ap=___) at subversion/libsvn_ra_svn/marshal.c:NNN
+  NNN                                 "Malformed network data");
+</pre>
+
+<p>There are several bits of useful information:</p>
+
+<ul>
+<li><p>A backtrace will tell you exactly what protocol exchange is
+    failing.</p>
+</li>
+
+<li><p>"print *conn" will show you the connection buffer.  read_buf,
+    read_ptr, and read_end represent the read buffer, which can
+    show
+    you the data the marshaller is looking at.  (Since read_buf isn't
+    generally 0-terminated at read_end, be careful of falsely assuming
+    that there's garbage data in the buffer.)</p>
+</li>
+
+<li><p>The format string determines what the marshaller was expecting to
+    see.</p>
+</li>
+</ul>
+
+<p>To debug the server in daemon mode, pull it up in gdb, set a
+breakpoint (usually a "Connection closed unexpectedly" error on the
+client indicates a "Malformed network data" error on the server,
+although it can also indicate a core dump), and run it with the "-X"
+option to serve a single connection:</p>
+
+<pre>
+  % gdb svnserve
+  (gdb) break marshal.c:NNN
+  (gdb) run -X
+</pre>
+
+<p>Then run the offending client command.  From there, it's just like
+debugging the client.</p>
+
+<p>Debugging the server in tunnel mode is more of a pain.  You'll need
+to stick something like "{ int x = 1; while (x); }" near the top of
+svnserve's main() and put the resulting svnserve in the user path on
+the server.  Then start an operation, gdb attach the process on the
+server, "set x = 0", and step through the code as desired.</p>
+
+</div> <!-- debugging-ra-svn -->
+
+</div> <!-- server-debugging -->
+
+
+<div class="h2" id="net-trace" title="net-trace">
+<h2>Tracing network traffic</h2>
+
+<p>Use <a href="http://www.wireshark.org/">Wireshark</a> (formerly
+known as "Ethereal") to eavesdrop on the conversation.</p>
+
+<p>First, make sure that between captures within the same wireshark
+session, you hit <em>Clear</em>, otherwise filters from one capture
+(say, an HTTP capture) might interfere with others (say, an ra_svn
+capture). </p>
+
+<p>Assuming you're cleared, then:</p>
+
+<ol>
+<li><p>Pull down the <i>Capture</i> menu, and choose
+    <i>Capture&nbsp;Filters</i>.</p></li>
+<li><p>If debugging the http:// (WebDAV) protocol, then in the window
+    that pops up, choose "<code>HTTP&nbsp;TCP&nbsp;port&nbsp;(80)</code>"
+    (which should result in the filter string
+    "<code><i>tcp&nbsp;port&nbsp;http</i></code>").</p>
+    <p>If debugging the svn:// (ra_svn) protocol, then choose <i>New</i>,
+    give the new filter a name (say, "ra_svn"), and type
+    "<code>tcp&nbsp;port&nbsp;3690</code>" into the filter string box.</p>
+    <p>When done, click OK.</p></li> 
+<li><p>Again go to the <i>Capture</i> menu, this time choose
+    <i>Interfaces</i>, and click <i>Options</i> next to the
+    appropriate interface (probably you want interface "lo", for
+    "loopback", assuming the server will run on the same machine as
+    the client).</p></li>
+<li><p>Turn off promiscuous mode by unchecking the appropriate
+    checkbox.</p></li>
+<li><p>Click the <i>Start</i> button in the lower right to start the
+    capture.</p></li>
+<li><p>Run your Subversion client.</p></li>
+<li><p>Click the Stop icon (a red X over an ethernet interface card) when
+    the operation is finished (or <i>Capture-&gt;Stop</i> should
+    work).  Now you have a capture.  It looks like a huge list of
+    lines.</p></li>
+<li><p>Click on the <i>Protocol</i> column to sort.</p></li>
+<li><p>Then, click on the first relevant line to select it; usually this
+    is just the first line.</p></li>
+<li><p>Right click, and choose <i>Follow TCP Stream</i>.  You'll be
+    presented with the request/response pairs of the Subversion
+    client's HTTP conversion.</p></li>
+</ol>
+
+<p>The above instructions are specific to the graphical version of
+Wireshark (version 0.99.6), and don't apply to the command-line
+version known as "tshark" (which corresponds to "tethereal", from back
+when Wireshark was called Ethereal).</p>
+
+<p>Alternatively, you may set the <tt>neon-debug-mask</tt> parameter in your
+<tt>servers</tt> configuration file to cause neon's debugging output
+to appear when you run the <tt>svn</tt> client.  The numeric value of
+<tt>neon-debug-mask</tt> is a combination of the <tt>NE_DBG_...</tt> values
+in the header file <tt>ne_utils.h</tt>.  For current versions of neon, setting
+<tt>neon-debug-mask</tt> to 130 (i.e. <tt>NE_DBG_HTTP+NE_DBG_HTTPBODY)</tt>
+will cause the HTTP data to be shown.</p>
+
+<p>You may well want to disable compression when doing a network
+trace&nbsp;&mdash; see the <tt>http-compression</tt> parameter in the
+<tt>servers</tt> configuration file.</p>
+
+<p>Another alternative is to set up a logging proxy between the
+Subversion client and server.  A simple way to do this is to use the
+<tt>socat</tt> program.  For example, to log communication with an
+svnserve instance, run the following command:</p>
+
+<p><tt>socat -v  TCP4-LISTEN:9630,reuseaddr,fork
+    TCP4:localhost:svn</tt></p>
+
+<p>Then run your svn commands using an URL base of
+<tt>svn://127.0.0.1:9630/</tt>; <tt>socat</tt> will forward the
+traffic from port 9630 to the normal svnserve port (3690), and will
+print all traffic in both directions to standard error, prefixing it
+with &lt; and &gt; signs to show the direction of the traffic.</p>
+
+</div> <!-- net-trace -->
+
+
+<div class="h2" id="tracing-memory-leaks" title="tracing-memory-leaks">
+<h2>Tracking down memory leaks</h2>
+
+<p>Our use of APR pools makes it unusual for us to have memory leaks
+in the strictest sense; all the memory we allocate will be cleaned up
+eventually.  But sometimes an operation takes more memory than it
+should; for instance, a checkout of a large source tree should not use
+much more memory than a checkout of a small source tree.  When that
+happens, it generally means we're allocating memory from a pool whose
+lifetime is too long.</p>
+
+<p>If you have a favorite memory leak tracking tool, you can configure
+with --enable-pool-debug (which will make every pool allocation use
+its own malloc()), arrange to exit in the middle of the operation, and
+go to it.  If not, here's another way:</p>
+
+<ul>
+
+<li><p>Configure with --enable-pool-debug=verbose-alloc.  Make sure to
+       rebuild all of APR and Subversion so that every allocation gets
+       file-and-line information.</p>
+</li>
+
+<li><p>Run the operation, piping stderr to a file.  Hopefully you have
+      lots of disk space.</p>
+</li>
+
+<li><p>In the file, you'll see lots of lines which look like:</p>
+
+   <pre>
+    POOL DEBUG: [5383/1024] PCALLOC (      2763/      2763/      5419) \
+    0x08102D48 "subversion/svn/main.c:612"                             \
+    &lt;subversion/libsvn_subr/auth.c:122&gt; (118/118/0)
+   </pre>
+
+    <p>What you care about most is the tenth field (the one in
+       quotes), which gives you the file and line number where the
+       pool for this allocation was created.  Go to that file and line
+       and determine the lifetime of the pool.  In the example above,
+       main.c:612 indicates that this allocation was made in the
+       top-level pool of the svn client.  If this were an allocation
+       which was repeated many times during the course of an
+       operation, that would indicate a source of a memory leak.  The
+       eleventh field (the one in brackets) gives the file and line
+       number of the allocation itself.</p>
+</li>
+
+</ul>
+
+</div> <!-- tracing-memory-leaks -->
+
+</div> <!-- debugging -->

Propchange: subversion/site/publish/docs/community-guide/debugging.part.html
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: subversion/site/publish/docs/community-guide/debugging.part.html
------------------------------------------------------------------------------
    svn:executable = *

Propchange: subversion/site/publish/docs/community-guide/debugging.part.html
------------------------------------------------------------------------------
    svn:keywords = Date

Propchange: subversion/site/publish/docs/community-guide/debugging.part.html
------------------------------------------------------------------------------
    svn:mime-type = text/html

Added: subversion/site/publish/docs/community-guide/debugging.toc.html
URL: http://svn.apache.org/viewvc/subversion/site/publish/docs/community-guide/debugging.toc.html?rev=906405&view=auto
==============================================================================
--- subversion/site/publish/docs/community-guide/debugging.toc.html (added)
+++ subversion/site/publish/docs/community-guide/debugging.toc.html Thu Feb  4 08:56:04 2010
@@ -0,0 +1,7 @@
+  <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>

Propchange: subversion/site/publish/docs/community-guide/debugging.toc.html
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: subversion/site/publish/docs/community-guide/debugging.toc.html
------------------------------------------------------------------------------
    svn:executable = *

Propchange: subversion/site/publish/docs/community-guide/debugging.toc.html
------------------------------------------------------------------------------
    svn:keywords = Date

Propchange: subversion/site/publish/docs/community-guide/debugging.toc.html
------------------------------------------------------------------------------
    svn:mime-type = text/html

Added: subversion/site/publish/docs/community-guide/general.html
URL: http://svn.apache.org/viewvc/subversion/site/publish/docs/community-guide/general.html?rev=906405&view=auto
==============================================================================
--- subversion/site/publish/docs/community-guide/general.html (added)
+++ subversion/site/publish/docs/community-guide/general.html Thu Feb  4 08:56:04 2010
@@ -0,0 +1,21 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" 
+   "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Apache Subversion - Community Guide - General Overview</title>
+<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
+<style type="text/css">
+  @import url("/style/site.css");
+  @import url("/docs/community-guide/guide.css");
+</style>
+</head>
+
+<body>
+<!--#include virtual="/site-banner.html" -->
+<!--#include virtual="/docs/community-guide/guide-nav.html" -->
+<div id="site-content">
+<!--#include virtual="/site-notice.html" -->
+
+<!--#include virtual="/docs/community-guide/general.part.html"-->
+</body>
+</html>

Propchange: subversion/site/publish/docs/community-guide/general.html
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: subversion/site/publish/docs/community-guide/general.html
------------------------------------------------------------------------------
    svn:executable = *

Propchange: subversion/site/publish/docs/community-guide/general.html
------------------------------------------------------------------------------
    svn:mime-type = text/html



Mime
View raw message