On Wed, Dec 23, 2009 at 09:35:23AM -0600, Hyrum K. Wright wrote:
> A little late, but never never, here's the promised tarballs for Subversion 1.6.7. The magic revision is r893529, and you can find the tarballs here:
>
> http://orac.ece.utexas.edu/pub/svn/1.6.7/
Not sure if we care, but hacking.html_at_r893529 and hacking.html from
the 1.6.7 tarball are different:
diff -urN svn-1.6.x_at_r893529/www/hacking.html svn-1.6.7/www/hacking.html
--- svn-1.6.x_at_r893529/www/hacking.html Wed Jan 14 16:54:58 2009
+++ svn-1.6.7/www/hacking.html Mon Nov 9 02:35:07 2009
@@ -22,7 +22,7 @@
this first.</p>
<pre>
-$LastChangedDate: 2009-01-14 16:54:58 +0000 (Wed, 14 Jan 2009) $
+$LastChangedDate: 2009-11-09 02:35:07 +0000 (Mon, 09 Nov 2009) $
</pre>
@@ -38,6 +38,7 @@
<li>Theory and documentation</li>
<li>Code to read</li>
<li>Directory layout</li>
+<li>Code modularity and interface visibility</li>
<li>Coding style</li>
<li>Secure coding guidelines</li>
<li>Destruction of stacked resources</li>
@@ -77,7 +78,7 @@
<p>Although Subversion is originally sponsored and hosted by CollabNet
(http://www.collab.net), it's a
-true open-source project under a BSD-style license. A number of
+true open-source project under the Apache License, Version 2.0. A number of
developers work for CollabNet, some work for other large companies
(such as RedHat), and many others are simply excellent volunteers who
are interested in building a better version control system.</p>
@@ -96,8 +97,8 @@
The "svn" list receives automated commit emails.</p></li>
<li><p>Get a copy of the latest development sources from
- <a href="http://svn.collab.net/repos/svn/trunk/"
- >http://svn.collab.net/repos/svn/trunk/</a>.
+ <a href="https://svn.collab.net/repos/svn/trunk/"
+ >https://svn.collab.net/repos/svn/trunk/</a>
<br />
New development always takes place on trunk. Bugfixes,
enhancements, and new features are backported from there to the
@@ -237,8 +238,10 @@
</li>
</ol>
-<p>Subversion tries to stay portable by using only ANSI/ISO C and by
-using the Apache Portable Runtime (APR) library. APR is the
+<p>Subversion tries to stay portable by using
+only ANSI/ISO C
+(a.k.a C90) 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>
@@ -343,7 +346,48 @@
</div>
+<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>
+
<div class="h2" id="coding-style" title="coding-style">
<h2>Coding style</h2>
@@ -870,20 +914,41 @@
it at the start of each iteration, then destroy it after the loop
is done, like so:</p>
<pre>
- apr_pool_t *subpool = svn_pool_create(pool);
+ apr_pool_t *iterpool = svn_pool_create(scratch_pool);
for (i = 0; i < n; ++i)
{
- svn_pool_clear(subpool);
- do_operation(..., subpool);
+ svn_pool_clear(iterpool);
+ do_operation(..., iterpool);
}
- svn_pool_destroy(subpool);
+ svn_pool_destroy(iterpool);
</pre>
</li>
</ol>
-<p>By using a loop subpool for loop-bounded data, you ensure O(1) instead
+<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
@@ -900,21 +965,22 @@
code:</p>
<pre>
- apr_hash_t *persistent_objects = apr_hash_make(pool);
- apr_pool_t *subpool = svn_pool_create(pool);
+ 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(subpool);
- SVN_ERR(do_something(&intermediate_result, ..., subpool));
- SVN_ERR(get_result(intermediate_result, &key, &val, ..., pool));
+ 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(subpool);
+ svn_pool_destroy(iterpool);
return persistent_objects;
</pre>
@@ -1081,7 +1147,7 @@
<pre>
error = some_routine(foo);
if (error)
- return (error);
+ return svn_error_return(error);
</pre>
<p>Actually, a better way to do this would be with the
@@ -1160,8 +1226,28 @@
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>
@@ -1190,8 +1276,8 @@
<p>Lieven Govaerts has set up a
<a href="http://buildbot.sourceforge.net/" >BuildBot</a> build/test
-farm at <a href="http://www.mobsol.be/buildbot/"
->http://www.mobsol.be/buildbot/</a>, see his message</p>
+farm at <a href="http://buildbot.subversion.org/buildbot/"
+>http://buildbot.subversion.org/buildbot/</a>, see his message</p>
<pre>
<a href="http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgNo=114212">http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgNo=114212</a>
@@ -1980,8 +2066,8 @@
experience or commit access. Expertise in using one's mail reading
software is optional, but recommended :-).</p>
-<p>The current patch manager is Daniel Shahaf
-<danielsh_at_tigris.org>.</p>
+<p>The current patch manager is Gavin 'Beau' Baumanis
+<gavin_at_thespidernet.com>.</p>
</div>
@@ -2341,6 +2427,22 @@
</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>
@@ -2538,14 +2640,46 @@
-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 "default revert mode".
+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>
<div class="h2" id="releasing" title="releasing">
<h2>How to release a distribution tarball</h2>
-<p>See The Subversion Release Procedure.</p>
+<p>See The Subversion Release Procedure
+for a description of how to create a release tarball.</p>
+<p>For an enlightening case study of the bungled Subversion 1.5 release
+cycle, see <a href="http://www.hyrumwright.org/papers/floss2009.pdf">this
+paper</a>.</p>
+
</div>
@@ -2785,8 +2919,8 @@
latest trunk, for example:</p>
<pre>
- $ svn cp http://svn.collab.net/repos/svn/trunk \
- http://svn.collab.net/repos/svn/branches/A.B.x
+ $ svn cp https://svn.collab.net/repos/svn/trunk \
+ https://svn.collab.net/repos/svn/branches/A.B.x
</pre>
<p>The stabilization period for a new A.B.0 release normally lasts
@@ -2799,7 +2933,8 @@
those language bindings may be tested.</p>
<p>At the beginning of the final week of the stabilization period, a
-new release candidate tarball should be made if there are any changes
+new release candidate tarball should be made if there are any
+showstopper changes
pending since the last one. The final week of the stabilization
period is reserved for critical bugfixes; fixes for minor bugs should
be deferred to the A.B.1 release. A critical bug is a non-edge-case
@@ -2953,6 +3088,28 @@
are following the change and might be willing to spend more time on
it.</p>
+<p>When votes are listed in the STATUS file, they are placed into a
+section for a given release. Some developers may want to vote the
+change into a <b>later</b> release, if (for example) they believe it
+requires further review or testing. Simply add a comment along with
+your vote:</p>
+
+<pre>
+ * r12345
+ Fiddle with the hoobey-gidget to clean the garblesnarf.
+ Justification:
+ All hell breaks loose if the jobbywonk gets out.
+ Votes:
+ +1: brane
+ +1: gstein (for 1.7.2)
+</pre>
+
+<p>Since votes are tied to specific releases (specified by the section
+they fall under), be very careful when moving change candidates among
+the sections. Existing votes were for the <b>original</b> version, not
+where the candidate has been moved it. Annotate existing votes as
+being cast only for the original version.</p>
+
<p>There is a somewhat looser voting system for areas that are not
core code, and that may have fewer experts available to review changes
(for example, tools/, packages/, bindings/, test scripts, etc.). A
@@ -3060,8 +3217,12 @@
release manager, and thus can be signed as described above.
To verify that the files are identical, you may use either the MD5 checksums
or the release manager's signature, both of which should be provided with the
-tarballs.
-</p>
+tarballs.</p>
+
+<p>But, if the checksum is not identical it doesn't have to be the case that
+the file signature is wrong, or the file has been tampered with. It could very
+well be the case that you don't have an identical gzip version as the release
+manager.</p>
</div>
<div class="h2" id="custom-releases" title="custom-releases">
@@ -3160,9 +3321,8 @@
href="http://subversion.tigris.org/servlets/ProjectMailingListList"
><em>l10n-??@subversion.tigris.org</em></a>).</p>
-<p>See <a href="http://svn.collab.net/repos/svn/trunk/TRANSLATING"
->http://svn.collab.net/repos/svn/trunk/TRANSLATING</a> for more
-information about translating.</p>
+<p>See the Guide to Translating Subversion for
+more information about translating.</p>
</div>
Received on 2009-12-26 16:33:41 CET