You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@subversion.apache.org by pe...@apache.org on 2010/01/20 17:31:57 UTC
svn commit: r901264 -
/subversion/site/publish/docs/community-guide/index.html
Author: peters
Date: Wed Jan 20 16:31:57 2010
New Revision: 901264
URL: http://svn.apache.org/viewvc?rev=901264&view=rev
Log:
Updates and cleanups to the Community Guide.
* site/publish/docs/community-guide/index.html:
(everywhere): Replace svn.collab.net/repos/svn/ with ^/, if
applicable, or svn.apache.org/repos/asf/subversion/. Replace
— with — and a normal space.
(#apr-pools): Replace " - " with ": " in list of pool types.
(#log-messages): Update r20946 citation to r861020.
(#reporting-bugs): Replace "#patch" link text with "patch submission
guidelines", the title of the section.
(#release-branches): Update the example changelog with a year "20XX"
instead of "200X", for Y2010 compliance.
(#porting-changes): Remove text "of the hacking guide".
Modified:
subversion/site/publish/docs/community-guide/index.html
Modified: subversion/site/publish/docs/community-guide/index.html
URL: http://svn.apache.org/viewvc/subversion/site/publish/docs/community-guide/index.html?rev=901264&r1=901263&r2=901264&view=diff
==============================================================================
--- subversion/site/publish/docs/community-guide/index.html (original)
+++ subversion/site/publish/docs/community-guide/index.html Wed Jan 20 16:31:57 2010
@@ -174,8 +174,8 @@
The "svn" list receives automated commit emails.</p></li>
<li><p>Get a copy of the latest development sources from
- <a href="https://svn.collab.net/repos/svn/trunk/"
- >https://svn.collab.net/repos/svn/trunk/</a>
+ <a href="https://svn.apache.org/repos/asf/subversion/trunk/"
+ >https://svn.apache.org/repos/asf/subversion/trunk/</a>
<br />
New development always takes place on trunk. Bugfixes,
enhancements, and new features are backported from there to the
@@ -254,7 +254,7 @@
"http://" or "https://".</p>
<p>The <a
-href="http://svn.collab.net/repos/svn/trunk/subversion/libsvn_ra_svn/protocol"
+href="http://svn.apache.org/repos/asf/subversion/trunk/subversion/libsvn_ra_svn/protocol"
>SVN Protocol</a> document contains a formal description of
Subversion ra_svn network protocol, which is a custom protocol
on port 3690 (by default), whose URLs begin with "svn://" or
@@ -277,9 +277,9 @@
<li><p>System notes</p>
<p>A lot of the design ideas for particular aspects of the system
- have been documented in individual files in the
- <a href="http://svn.collab.net/repos/svn/trunk/notes/">notes/</a>
- directory.</p>
+ have been documented in individual files in the <a
+ href="http://svn.apache.org/repos/asf/subversion/trunk/notes/"
+ >notes/</a> directory.</p>
</li>
</ol>
@@ -294,7 +294,7 @@
with the existing code base and interfaces.</p>
<p>Check out a copy of Subversion (anonymously, if you don't yet have
-an account with commit access) — so you can look at
+an account with commit access) — so you can look at
the code.</p>
<p>Within 'subversion/include/' are a bunch of header files with huge
@@ -436,7 +436,7 @@
certainly be test-suite ready.</p>
<p>We also strongly prefer to see large changes broken up into
-several, smaller, logical commits — each of which is expected
+several, smaller, logical commits — each of which is expected
to meet the aforementioned requirements of stability.</p>
<p>That said, we understand that it can be nearly impossible to apply
@@ -466,7 +466,7 @@
<p>If you're working on a feature or bugfix in stages involving
multiple commits, and some of the intermediate stages aren't stable
enough to go on trunk, then create a temporary branch in /branches.
-There's no need to ask — just do it. It's fine to try
+There's no need to ask — just do it. It's fine to try
out experimental ideas in a temporary branch, too. And all the
preceding applies to partial as well as full committers.</p>
@@ -484,8 +484,8 @@
on that branch, and reviewers shouldn't have to spend time figuring
out which ones they are.</p>
-<p>When you're done with the branch — when you've
-either merged it to trunk or given up on it — please
+<p>When you're done with the branch — when you've
+either merged it to trunk or given up on it — please
remember to remove it.</p>
<p>See also the <a href="#partial-commit-access" >section on partial
@@ -625,7 +625,7 @@
<p>Read over the Subversion code to get an overview of how documentation looks
in practice; in particular, see
-<a href="http://svn.collab.net/repos/svn/trunk/subversion/include/">
+<a href="http://svn.apache.org/repos/asf/subversion/trunk/subversion/include/">
subversion/include/*.h</a> for doxygen examples.
</p>
@@ -683,7 +683,7 @@
mail.</p>
<p>A patch submission should contain one logical change; please don't
-mix N unrelated changes in one submission — send N
+mix N unrelated changes in one submission — send N
separate emails instead.</p>
<p>Generate the patch using <tt>svn diff</tt> from the top of a
@@ -731,13 +731,13 @@
feature completely in your mail; if the patch fixes a bug, describe
the bug in detail and give a reproduction recipe. An exception to
these guidelines is when the patch addresses a specific issue in the
-issues database — in that case, just refer to the
+issues database — in that case, just refer to the
issue number in your log message, as described
in <a href="#log-messages">Writing log messages</a>.</p>
<p>It is normal for patches to undergo several rounds of feedback and
change before being applied. Don't be discouraged if your patch is
-not accepted immediately — it doesn't mean you goofed,
+not accepted immediately — it doesn't mean you goofed,
it just means that there are a <em>lot</em> of eyes looking at every
code submission, and it's a rare patch that doesn't have at least a
little room for improvement. After reading people's responses to your
@@ -775,7 +775,7 @@
regardless of its source, not every person who contributes code to
Subversion will earn commit access.</p>
-<p>The <a href="http://svn.collab.net/repos/svn/trunk/COMMITTERS"
+<p>The <a href="http://svn.apache.org/repos/asf/subversion/trunk/COMMITTERS"
>COMMITTERS</a> file lists all committers, both full and partial, and
says the domains for each partial committer.</p>
@@ -849,8 +849,8 @@
experimental branch at any time. It is not necessary that the
experimental branch have a high likelihood of being merged to trunk
(although that's always a good goal to aim for). It's just as
-important that the full committer — all the full
-committers, actually — view such branches as training
+important that the full committer — all the full
+committers, actually — view such branches as training
grounds for new developers, by giving feedback on the commits. The
goal of these branches is both to get new code into Subversion and to
get new developers into the project. See also the <a
@@ -890,7 +890,7 @@
<p>Any committer, whether full or partial, may commit fixes for
obvious typos, grammar mistakes, and formatting problems wherever they
-may be — in the web pages, API documentation, code
+may be — in the web pages, API documentation, code
comments, commit messages, etc. We rely on the committer's judgement
to determine what is "obvious"; if you're not sure, just ask.</p>
@@ -1191,18 +1191,18 @@
<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
+<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
+<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,
+<li><p><code>iterpool</code>: An <em>iteration</em> pool, used inside loops,
as per the above example.</p></li>
</ul>
@@ -1284,7 +1284,7 @@
to not worry so much about individual allocations, but rather about
overall performance and lifetime groups. Instead, foo_t generally
should not have a `pool' field. Just allocate as many foo objects as
-you need in the current pool — when that pool gets
+you need in the current pool — when that pool gets
cleared or destroyed, they will all go away simultaneously.</p>
<p>See also the <a href="#exception-handling">Exception handling</a>
@@ -1759,7 +1759,7 @@
individual authors (i.e., we don't put lines like
"Author: foo" or "@author foo" in a special position
at the top of a source file). This is to discourage
- territoriality — even when a file has only one
+ territoriality — even when a file has only one
author, we want to make sure others feel free to make changes.
People might be unnecessarily hesitant if someone appears to
have staked a personal claim to the file.</p>
@@ -1865,7 +1865,7 @@
changes within a file are grouped by symbol, with the symbols listed
in parentheses followed by a colon, followed by text describing the
change. Please adhere to this format, even when only one file is
-changed — not only does consistency aid readability,
+changed — not only does consistency aid readability,
it also allows software to colorize log entries automatically.</p>
<p>As an exception to the above, if you make exactly the same change
@@ -1963,7 +1963,7 @@
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
-r20946 for an example.</p>
+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
@@ -1990,8 +1990,8 @@
<p>It is very important to record code contributions in a consistent
and parseable way. This allows us to write scripts to figure out who
-has been actively contributing — and what they have
-contributed — so we can <a
+has been actively contributing — and what they have
+contributed — so we can <a
href="http://www.red-bean.com/svnproject/contribulyzer/">spot
potential new committers quickly</a>. The Subversion project uses
human-readable but machine-parseable fields in log messages to
@@ -2011,11 +2011,11 @@
</pre>
<p>If multiple individuals wrote the patch, list them each on a
-separate line — making sure to start each continuation
+separate line — making sure to start each continuation
line with whitespace. Non-committers should be listed by name, if
known, and e-mail. Full and partial committers should be listed by
their canonical usernames from <a
-href="http://svn.collab.net/repos/svn/trunk/COMMITTERS"
+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>
@@ -2118,7 +2118,7 @@
"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 by: ", and from time to time someone may use
-a field that sounds official but really is not — for
+a field that sounds official but really is not — for
example, there are a few instances of "Reported by: ".
These are okay, but try to use an official field, or a parenthetical
aside, in preference to creating your own. Also, don't use
@@ -2369,9 +2369,9 @@
<p>For a description of how to use and add tests to Subversion's
automated test framework, please read <a
-href="http://svn.collab.net/repos/svn/trunk/subversion/tests/README"
+href="http://svn.apache.org/repos/asf/subversion/trunk/subversion/tests/README"
>subversion/tests/README</a> and <a
-href="http://svn.collab.net/repos/svn/trunk/subversion/tests/cmdline/README"
+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
@@ -2380,9 +2380,9 @@
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.collab.net/repos/svn/trunk/tools/test-scripts/svntest/"
+href="http://svn.apache.org/repos/asf/subversion/trunk/tools/test-scripts/svntest/"
>svntest</a> framework (start at the <a
-href="http://svn.collab.net/repos/svn/trunk/tools/test-scripts/svntest/README"
+href="http://svn.apache.org/repos/asf/subversion/trunk/tools/test-scripts/svntest/README"
>README</a>).</p>
</div> <!-- automated-tests -->
@@ -2646,8 +2646,8 @@
will cause the HTTP data to be shown.</p>
<p>You may well want to disable compression when doing a network
-trace—see the <tt>http-compression</tt> parameter in the <tt>servers</tt>
-configuration file.</p>
+trace — 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
@@ -2726,7 +2726,7 @@
<p>The advice below is based on years of experience with the
Subversion mailing lists, and addresses the problems seen most
frequently on those lists. It should <i>not</i> be taken as a
-complete guide to mailing list etiquette — you can <a
+complete guide to mailing list etiquette — you can <a
href="http://www.google.com/search?hl=en&ie=UTF-8&q=%22mailing+list+etiquette%22&btnG=Google+Search"
>find one of those on the Net</a> pretty easily if you want one.</p>
@@ -2739,7 +2739,7 @@
<p>When in doubt, mail <a href="mailto:users@subversion.apache.org"
>users@subversion.apache.org</a>, not dev@subversion.apache.org.
There are many experienced people (including some of Subversion's
-maintainers) on users@ list — they may be able to answer your
+maintainers) on users@ list — they may be able to answer your
question, or if you think you've found a bug they can determine
whether or not it is a genuine bug. You should even post to users@
when you want to suggest a new feature: many feature suggestions are
@@ -2755,7 +2755,7 @@
<p>Of course, if the mail is about a possible bug in Subversion, and
got no reaction on users@, then asking on dev@ is
-fine — bugs are a development topic.
+fine — bugs are a development topic.
And <a href="#patches" >patches</a> should always be sent directly to
dev@.</p>
@@ -2905,7 +2905,7 @@
them for this. If you must chide, do it gently, and certainly don't
bother to make an extra post just to point out a minor problem like
this. There are even situations where top-posting is
-preferable — for example, when the response is short
+preferable — for example, when the response is short
and general, and applies to the entirety of a long passage of quoted
text. So top-posting is always a judgement call, and in any case it's
not a major inconvenience even when done inappropriately.</p>
@@ -2940,7 +2940,7 @@
mails, RichText mails, or other formats that might be opaque to
text-only mailreaders. Regarding language: we don't have an
English-only policy, but you will probably get the best results by
-posting in English — it is the language shared by the
+posting in English — it is the language shared by the
greatest number of list participants.</p> <!-- Not bothering to
describe the exact headers we expect, but if we wanted to, it would be
something like:
@@ -2968,7 +2968,7 @@
use of an issue tracking tool to manage known outstanding issues with
the software. But perhaps <em>unlike</em> most software projects, we
try to keep our issue tracker relatively free of debris. It's not
-that we don't want to hear about Subversion's problems — after
+that we don't want to hear about Subversion's problems — after
all, we can't fix what we don't know is broken. It's just that we've
found a mismanaged issue tracker to be more of a hindrance than a
help.</p>
@@ -3082,9 +3082,8 @@
obvious to someone else, so it's best to avoid a guessing game.
Follow that with the environment description, and the reproduction
recipe. If you also want to include speculation as to the cause, and
-even a patch to fix the bug, that's great — see <a
-href="#patches">#patches</a> for instructions
-on sending patches.</p>
+even a patch to fix the bug, that's great — see the <a
+href="#patches">patch submission guidelines</a>.</p>
<p>Post all of this information to <a
href="mailto:dev@subversion.apache.org"
@@ -3318,7 +3317,7 @@
1.2.0 --> next stable minor release after that
</pre>
-<p>The order of releases is semi-nonlinear — a 1.0.3
+<p>The order of releases is semi-nonlinear — a 1.0.3
<em>might</em> come out after a 1.1.0. But it's only "semi"-nonlinear
because eventually we declare a patch line defunct and tell people to
upgrade to the next minor release, so over the long run the numbering
@@ -3450,8 +3449,8 @@
latest trunk, for example:</p>
<pre>
- $ svn cp https://svn.collab.net/repos/svn/trunk \
- https://svn.collab.net/repos/svn/branches/A.B.x
+ $ svn cp https://svn.apache.org/repos/asf/subversion/trunk \
+ https://svn.apache.org/repos/asf/subversion/branches/A.B.x
</pre>
<p>The stabilization period for a new A.B.0 release normally lasts
@@ -3782,7 +3781,7 @@
that would not be relevant to mainline Subversion, please stay in
touch with the users of the custom release so you can intercept and
filter those reports. But of course, the best option would be not to
-be in that situation in the first place — the more
+be in that situation in the first place — the more
your custom release diverges from mainline Subversion, the more
confusion it invites. If you must make custom releases, please try to
keep them as temporary and as non-divergent as possible.</p>
@@ -3817,8 +3816,8 @@
<ul>
<li><p>Create the new release branch with a server-side copy:</p>
<pre>
- svn cp http://svn.apache.org/repos/asf/subversion/trunk \
- http://svn.apache.org/repos/asf/subversion/branches/A.B.x \
+ svn cp https://svn.apache.org/repos/asf/subversion/trunk \
+ https://svn.apache.org/repos/asf/subversion/branches/A.B.x \
-m "Create A.B.x release branch."
</pre></li>
@@ -3864,7 +3863,7 @@
<p>The protocol used to accept or refuse the merging of changes from
trunk is of interest to all Subversion developers, and as such is
documented in <a href="#release-stabilization">the
-release stabilization section of the hacking guide</a>.</p>
+release stabilization section</a>.</p>
</div> <!-- porting-changes -->
@@ -4084,7 +4083,7 @@
h) Then test that you can check out the Subversion repository
with this environment:
- subversion/svn/svn co https://svn.collab.net/repos/svn/trunk
+ subversion/svn/svn co https://svn.apache.org/repos/asf/subversion/trunk
i) Verify that the perl and python swig bindings at least compile.
If you can't do this, then have another developer verify.
@@ -4138,8 +4137,7 @@
svn up -r 1234
svnversion .
cp svn_version.h.dist subversion/include/svn_version.h
- svn cp . \
- https://svn.apache.org/repos/asf/subversion/tags/X.Y.Z \
+ svn cp . ^/subversion/tags/X.Y.Z \
-m "Tagging release X.Y.Z with svn_version.h matching tarball"
</pre>
@@ -4266,8 +4264,8 @@
<p>Translation has been divided into two domains. First, there is the
translation of server messages sent to connecting clients. This issue
has been <a
-href="http://svn.collab.net/repos/svn/trunk/notes/l10n-problems">punted
-for now</a>. Second there is the translation of the client and its
+href="http://svn.apache.org/repos/asf/subversion/trunk/notes/l10n-problems"
+>punted for now</a>. Second there is the translation of the client and its
libraries.</p>
@@ -4321,8 +4319,8 @@
string composition.</p>
<p>Currently available translations can be found in <a
-href="http://svn.collab.net/repos/svn/trunk/subversion/po/" >the po
-section of the repository</a>. Please contact
+href="http://svn.apache.org/repos/asf/subversion/trunk/subversion/po/"
+>the po section of the repository</a>. Please contact
dev@subversion.tigris.org when you want to start a translation not
available yet. Translation discussion takes place both on that list
and on dedicated native language mailing lists (<a
@@ -4544,7 +4542,7 @@
<p>Merging messages from trunk revision X of YY.po to your branch working
copy can be done with this command:</p>
<pre>
- svn cat -r X http://svn.collab.net/repos/svn/trunk/subversion/po/YY.po | \
+ svn cat -r X ^/subversion/trunk/subversion/po/YY.po | \
po-merge.py YY.po
</pre>
@@ -4555,9 +4553,10 @@
<h2>Requirements for po and mo files</h2>
<p>On some gettext implementations we have to ensure that the mo
-files—whether obtained through the project or created locally—are
-encoded using UTF-8. This requirement stem from the fact that Subversion uses
-UTF-8 internally, some implementations translate to the active locale
+files — whether obtained through the project or created
+locally — are encoded using UTF-8. This requirement stems
+from the fact that Subversion uses UTF-8 internally, some
+implementations translate to the active locale
and the fact that <code>bind_textdomain_codeset()</code> is not portable
across implementations.</p>
Re: svn commit: r901264 - /subversion/site/publish/docs/community-guide/index.html
Posted by "C. Michael Pilato" <cm...@collab.net>.
peters@apache.org wrote:
> Author: peters
> Date: Wed Jan 20 16:31:57 2010
> New Revision: 901264
>
> URL: http://svn.apache.org/viewvc?rev=901264&view=rev
> Log:
> Updates and cleanups to the Community Guide.
THANK YOU!
--
C. Michael Pilato <cm...@collab.net>
CollabNet <> www.collab.net <> Distributed Development On Demand
Re: svn commit: r901264 - /subversion/site/publish/docs/community-guide/index.html
Posted by "C. Michael Pilato" <cm...@collab.net>.
peters@apache.org wrote:
> Author: peters
> Date: Wed Jan 20 16:31:57 2010
> New Revision: 901264
>
> URL: http://svn.apache.org/viewvc?rev=901264&view=rev
> Log:
> Updates and cleanups to the Community Guide.
THANK YOU!
--
C. Michael Pilato <cm...@collab.net>
CollabNet <> www.collab.net <> Distributed Development On Demand