subversion-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cmpil...@apache.org
Subject svn commit: r900994 - in /subversion: site/publish/docs/hacking/index.html trunk/www/mailing-lists.html
Date Tue, 19 Jan 2010 22:53:55 GMT
Author: cmpilato
Date: Tue Jan 19 22:53:54 2010
New Revision: 900994

URL: http://svn.apache.org/viewvc?rev=900994&view=rev
Log:
* trunk/www/mailing-lists.html
  Move the etiquette portion of this document...

* site/publish/docs/hacking/index.html
  ...into a new "chapter" of this one.

Modified:
    subversion/site/publish/docs/hacking/index.html
    subversion/trunk/www/mailing-lists.html

Modified: subversion/site/publish/docs/hacking/index.html
URL: http://svn.apache.org/viewvc/subversion/site/publish/docs/hacking/index.html?rev=900994&r1=900993&r2=900994&view=diff
==============================================================================
--- subversion/site/publish/docs/hacking/index.html (original)
+++ subversion/site/publish/docs/hacking/index.html Tue Jan 19 22:53:54 2010
@@ -9,7 +9,7 @@
   font-family: serif;
   font-size: 12pt;
 }
-tt, pre {
+pre {
   font-size: 11pt;
 }
 .h1 {
@@ -88,6 +88,16 @@
       <li><a href="#tracing-memory-leaks">Tracking down memory leaks</a></li>
     </ol>
   </li>
+  <li><a href="#mailing-lists">Mailing Lists</a>
+    <ol>
+      <li><a href="#where-to-post">Where to post</a></li>
+      <li><a href="#when-to-post">When to post</a></li>
+      <li><a href="#formatting">Formatting</a></li>
+      <li><a href="#replying">Replying</a></li>
+      <li><a href="#sending-patches">Sending patches</a></li>
+      <li><a href="#encodings">Languages and encodings</a></li>
+    </ol>
+  </li>
   <li><a href="#issues">Bugs / Issues</a>
     <ol>
       <li><a href="#reporting-bugs">How to report a bug</a></li>
@@ -103,7 +113,7 @@
       <li><a href="#custom-releases">Custom releases</a></li>
       <li><a href="#release-branches">Creating and maintaining release branches</a></li>
       <li><a href="#porting-changes">Porting changes to release branches</a></li>
-      <li><a href="#the-changes-file">Managing the <tt>CHANGES file</tt></a></li>
+      <li><a href="#the-changes-file">Managing the CHANGES file</a></li>
       <li><a href="#before-release">Preparing to roll a release</a></li>
       <li><a href="#rolling-release">Rolling a release</a></li>
       <li><a href="#releasing-release">The actual releasing</a></li>
@@ -113,6 +123,7 @@
   </li>
   <li><a href="#l10n">Localization (l10n)</a>
     <ol>
+      <li><a href="#l10n-overview">Localization overview</a></li>
       <li><a href="#version-requirements">Software version requirements</a></li>
       <li><a href="#new-translation">Starting a new translation</a></li>
       <li><a href="#verifying">Verifying your po file</a></li>
@@ -2691,6 +2702,245 @@
 </div> <!-- debugging -->
 
 
+<div class="h1" id="mailing-lists" title="mailing-lists">
+<h1>Mailing Lists</h1>
+
+<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&nbsp;&mdash;&nbsp;you can <a
+href="http://www.google.com/search?hl=en&amp;ie=UTF-8&amp;q=%22mailing+list+etiquette%22&amp;btnG=Google+Search"
+>find one of those on the Net</a> pretty easily if you want one.</p>
+
+<p>If you follow these conventions when posting to our mailing lists,
+your post is much more likely to be read and answered.</p>
+
+<div class="h2" id="where-to-post" title="where-to-post">
+<h2>Where to post</h2>
+
+<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 &mdash; 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
+ideas that have been discussed before, and someone on the
+users@subversion.apache.org mailing list will usually be able to tell
+if that's the case with your suggestion.</p>
+
+<p>Please do <i>not</i> post to dev@ as a last resort after failing to
+get an answer on users@.  The two lists have different charters:
+users@ is a support forum, dev@ is a development discussion list.
+When a support question goes unanswered on users@, that is
+unfortunate, but it does not make the question appropriate for dev@.</p>
+
+<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&nbsp;&mdash;&nbsp;bugs are a development topic.
+And <a href="#patches" >patches</a> should always be sent directly to
+dev@.</p>
+
+</div> <!-- where-to-post -->
+
+
+<div class="h2" id="when-to-post" title="when-to-post">
+<h2>When to post</h2>
+
+<p>Sometimes, when really impassioned about a topic, it's tempting to
+respond to every message in a mail thread.  Please don't do this.  Our
+mailing lists are already high-traffic, and following up to every
+message only adds to the noise.</p>
+
+<p>Instead, read the entire mail thread, think carefully about what
+you have to say, pick a single message to reply to, and then lay out
+your thoughts.  Occasionally it might make sense to reply to two
+separate messages in a thread, but only if the topics have started to
+diverge.</p>
+
+</div> <!-- when-to-post -->
+
+
+<div class="h2" id="formatting" title="formatting">
+<h2>Formatting</h2>
+
+<div class="h3" id="line-length" title="line-length">
+<h3>Line Length</h3>
+
+<p>Please don't use lines longer than 72 columns.  Many people use
+80-column terminals to read their email.  By writing your text in 72
+columns, you leave room for quoting characters to be added in future
+replies without forcing a rewrapping of the text.  The 72-column limit
+only applies to the prose part of your message, of course.  If you're
+posting a patch, see <a href="#patches">the section on
+patches</a>.</p>
+
+<p>Some mailers do a kind of automatic line-wrapping, whereby when
+you're writing your mail, the display shows line breaks that aren't
+actually there.  When the mail reaches the list, it won't have the
+line breaks you thought it had.  If your mail editor does this, look
+for a setting you can tweak to make it show true line breaks.</p>
+
+</div> <!-- line-length -->
+
+<div class="h3" id="capitalization" title="capitalization">
+<h3>Capitalization</h3>
+
+<p>Capitalize the first letter of each sentence, and use paragraphs.
+If you're showing screen output or some other sort of example, offset
+it so it's clearly separate from the prose.  If you don't do these
+things, your mail will be <i>much</i> less readable than it could be,
+and many people will not bother to read it at all.</p>
+
+</div> <!-- capitalization -->
+
+</div> <!-- formatting -->
+
+
+<div class="h2" id="replying" title="replying">
+<h2>Replying</h2>
+
+<div class="h3" id="reply-to" title="reply-to">
+<h3>Reply-To</h3>
+
+<p>Make sure to use your mailreader's "Follow-up" or "Reply-to-all" or
+"Group reply" feature when responding to a list post.  Otherwise, your
+mail will only go to the author of the original post, not to the whole
+list.  Unless there's a reason to reply privately, it's always better
+to respond to the list, so everyone can watch and learn.  (Also, many
+people who frequently get private responses to their posts have
+indicated that they would prefer those responses to go to the list
+instead.)</p>
+
+<p>Note that the Subversion mailing lists do not modify the
+<tt>Reply-to</tt> header to redirect responses to the list.  They
+leave <tt>Reply-to</tt> set to whatever the original sender had, for
+the reasons listed in <a
+href="http://www.unicom.com/pw/reply-to-harmful.html"
+>http://www.unicom.com/pw/reply-to-harmful.html</a>, in particular the
+"Principle of Least Damage" and "Can't Find My Way Back Home"
+sections.  From time to time, someone posts asking why we don't set
+the <tt>Reply-to</tt> header.  Sometimes that person will mention <a
+href="http://www.metasystema.net/essays/reply-to.mhtml"
+>http://www.metasystema.net/essays/reply-to.mhtml</a>, which
+gives arguments in favor of modifying the <tt>Reply-to</tt> field.
+The list administrators are aware of both documents, and see that both
+sides of the argument have merits, but in the end have chosen not to
+modify the <tt>Reply-to</tt> headers.  Please don't resurrect the
+topic.</p>
+
+</div> <!-- reply-to -->
+
+<div class="h3" id="fresh-post" title="fresh-post">
+<h3>Making a fresh post</h3>
+
+<p>Don't start a new thread (subject) by replying to an existing
+post.  Instead, start a fresh mail, even if that means you have to
+write out the list address by
+hand.  If you reply to an existing post, your mailreader may include
+metadata that marks your post as a followup in that thread.  Changing
+the <tt>Subject</tt> header is not enough to prevent this!  Many
+mailreaders will still preserve enough metadata to put your post in
+the wrong thread.  If this happens, not only will some people not see
+your post (because they're ignoring that thread), but people who are
+reading the thread will waste their time with your off-topic post.
+The safest way to avoid this is to never use "reply" to start a new
+topic.</p>
+
+<p>(The root of the problem is really that some mail interfaces do
+not indicate that the message generated by the "Reply" function is
+different from a fresh message.  If you use such a program, consider
+submitting an enhancement request or a patch to its developers to make
+it show a distinction.)</p>
+
+</div> <!-- fresh-post -->
+
+<div class="h3" id="rethreading" title="rethreading">
+<h3>Re-threading</h3>
+
+<p>If you do need to change the <tt>Subject</tt> header while
+preserving the thread (perhaps because the thread has wandered into
+some other topic), do it by making a post under the new subject with
+the old subject in parenthesis, like this:</p>
+
+<pre>
+   Blue asparagus
+     |
+     |_ Re: Blue asparagus
+         |
+         |_ Yellow elephants (was: Re: Blue asparagus)    <i>&lt;-- ### switch
###</i>
+            |
+            |_ Re: Yellow elephants
+</pre>
+
+</div> <!-- rethreading -->
+
+<div class="h3" id="top-posting" title="top-posting">
+<h3>Top-Posting</h3>
+
+<p>Please don't reflexively chide people for top-posting.
+"Top-posting" is the practice of putting the response text above the
+quoted text, instead of interleaved with it or below it.  Usually, the
+quoted text provides essential context for understanding the response,
+and so top-posting is a hindrance.  Sometimes, people top-post when it
+would have been better to inter-post or bottom-post, and others chide
+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&nbsp;&mdash;&nbsp;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>
+
+<p>If you came here looking for advice on how to quote, instead of
+advice on how to not flame people for their bad quoting habits, see <a
+href="http://www.netmeister.org/news/learn2quote.html"
+>http://www.netmeister.org/news/learn2quote.html</a> (Deutsch:
+<a href="http://learn.to/quote">http://learn.to/quote</a>).</p>
+
+</div> <!-- top-posting -->
+
+</div> <!-- replying -->
+
+
+<div class="h2" id="sending-patches" title="sending-patches">
+<h2>Sending patches</h2>
+
+<p>See <a href="patches">here</a> for advice on how to send in a
+patch.  Note that you can send in a patch to modify these web pages as
+well as to modify code; the web pages' repository URL is
+<a href="http://svn.apache.org/repos/asf/subversion/site/"
+>http://svn.apache.org/repos/asf/subversion/site/</a>.</p>
+
+</div> <!-- sending-patches -->
+
+
+<div class="h2" id="encodings" title="encodings">
+<h2>Languages and encodings</h2>
+
+<p>Please use ASCII or ISO-8859 text if possible.  Don't post HTML
+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&nbsp;&mdash;&nbsp;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:
+   
+          Content-Type: text/plain; charset=iso-8859-1
+          Content-Type: text/plain; charset=iso-8859-15
+   
+        and
+   
+          Content-Transfer-Encoding: 8bit
+          Content-Transfer-Encoding: quoted-printable
+   -->
+
+</div> <!-- encodings -->
+
+</div> <!-- mailing-lists -->
+
+
 <div class="h1" id="issues" title="issues">
 <h1>Bugs / Issues</h1>
 
@@ -3602,7 +3852,7 @@
 
 
 <div class="h2" id="the-changes-file" title="the-changes-file">
-<h2>Managing the <tt>CHANGES file</tt></h2>
+<h2>Managing the CHANGES file</h2>
 
 <p>The <tt>CHANGES</tt> file is the project changelog file.  Before a
 release, it must be brought up to date to list all changes since the
@@ -3992,8 +4242,8 @@
 </div> <!-- releasing -->
 
 
-<div class="h2" id="l10n" title="l10n">
-<h2>Localization (l10n)</h2>
+<div class="h1" id="l10n" title="l10n">
+<h1>Localization (l10n)</h1>
 
 <p>Translation has been divided into two domains.  First, there is the
 translation of server messages sent to connecting clients.  This issue
@@ -4002,6 +4252,10 @@
 for now</a>.  Second there is the translation of the client and its
 libraries.</p>
 
+
+<div class="h2" id="l10n-overview" title="l10n-overview">
+<h2>Localization overview</h2>
+
 <p>The gettext package provides services for translating messages.  It
 uses the xgettext tool to extract strings from the sources for
 translation.  This works by extracting the arguments of the _(), N_() and
@@ -4057,6 +4311,9 @@
 href="http://subversion.tigris.org/servlets/ProjectMailingListList"
 ><em>l10n-??@subversion.tigris.org</em></a>).</p>
 
+</div> <!-- l10n-overview -->
+
+
 <div class="h2" id="version-requirements" title="version-requirements">
 <h2>Software version requirements</h2>
 

Modified: subversion/trunk/www/mailing-lists.html
URL: http://svn.apache.org/viewvc/subversion/trunk/www/mailing-lists.html?rev=900994&r1=900993&r2=900994&view=diff
==============================================================================
--- subversion/trunk/www/mailing-lists.html (original)
+++ subversion/trunk/www/mailing-lists.html Tue Jan 19 22:53:54 2010
@@ -134,239 +134,6 @@
 
 </div>  <!-- mailing-lists -->
 
-<div class="h2" id="etiquette" title="etiquette"/>
-<h2 style="text-align: center" >Mailing List Etiquette</h2>
-
-<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&nbsp;&mdash;&nbsp;you can <a
-href="http://www.google.com/search?hl=en&amp;ie=UTF-8&amp;q=%22mailing+list+etiquette%22&amp;btnG=Google+Search"
->find one of those on the Net</a> pretty easily if you want one.</p>
-
-<p>If you follow these conventions when posting to
-users@subversion.tigris.org or dev@subversion.tigris.org, your post is
-much more likely to be read and answered.</p>
-
-<div class="h3" id="where" title="where">
-<h3>Where to post:</h3>
-
-<p>When in doubt, mail <a href="mailto:users@subversion.tigris.org"
->users@subversion.tigris.org</a>, not dev@subversion.tigris.org.
-There are many experienced people (including some of Subversion's
-maintainers) on users@ list&nbsp;&mdash;&nbsp;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 ideas that have been discussed before, and someone on
-the users@subversion.tigris.org mailing list will usually be able to
-tell if that's the case with your suggestion.  </p>
-
-<p>Please do <i>not</i> post to dev@ as a last resort after failing to
-get an answer on users@.  The two lists have different charters:
-users@ is a support forum, dev@ is a development discussion list.
-When a support question goes unanswered on users@, that is
-unfortunate, but it does not make the question appropriate for dev@.</p>
-
-<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&nbsp;&mdash;&nbsp;bugs are a development topic.  And <a
-href="hacking.html#patches" >patches</a> should always be sent
-directly to dev@.</p>
-
-</div>  <!-- where -->
-
-<div class="h3" id="when" title="when">
-<h3>When to post</h3>
-
-<p>Sometimes, when really impassioned about a topic, it's tempting to
-respond to every message in a mail thread.  Please don't do this.  Our
-mailing lists are already high-traffic, and following up to every
-message only adds to the noise.</p>
-
-<p>Instead, read the entire mail thread, think carefully about what
-you have to say, pick a single message to reply to, and then lay out
-your thoughts.  Occasionally it might make sense to reply to two
-separate messages in a thread, but only if the topics have started to
-diverge.</p>
-
-</div>
-
-<div id="formatting" title="formatting">
-
-<div class="h3" id="line-length" title="line-length">
-<h3>Line Length</h3>
-
-<p>Please don't use lines longer than 72 columns.  Many people use
-80-column terminals to read their email.  By writing your text in 72
-columns, you leave room for quoting characters to be added in future
-replies without forcing a rewrapping of the text.  The 72-column limit
-only applies to the prose part of your message, of course.  If you're
-posting a patch, see <a href="#patches">the section on
-patches</a>.</p>
-
-<p>Some mailers do a kind of automatic line-wrapping, whereby when
-you're writing your mail, the display shows line breaks that aren't
-actually there.  When the mail reaches the list, it won't have the
-line breaks you thought it had.  If your mail editor does this, look
-for a setting you can tweak to make it show true line breaks.</p>
-
-</div>
-
-<div class="h3" id="capitalization" title="capitalization">
-<h3>Capitalization</h3>
-
-<p>Capitalize the first letter of each sentence, and use paragraphs.
-If you're showing screen output or some other sort of example, offset
-it so it's clearly separate from the prose.  If you don't do these
-things, your mail will be <i>much</i> less readable than it could be,
-and many people will not bother to read it at all.</p>
-
-</div>
-
-</div>
-
-<div id="replying" title="replying">
-
-<div class="h3" id="reply-to" title="reply-to">
-<h3>Reply-To</h3>
-
-<p>Make sure to use your mailreader's "Follow-up" or "Reply-to-all" or
-"Group reply" feature when responding to a list post.  Otherwise, your
-mail will only go to the author of the original post, not to the whole
-list.  Unless there's a reason to reply privately, it's always better
-to respond to the list, so everyone can watch and learn.  (Also, many
-people who frequently get private responses to their posts have
-indicated that they would prefer those responses to go to the list
-instead.)</p>
-
-<p>Note that the Subversion mailing lists do not modify the
-<tt>Reply-to</tt> header to redirect responses to the list.  They
-leave <tt>Reply-to</tt> set to whatever the original sender had, for
-the reasons listed in <a
-href="http://www.unicom.com/pw/reply-to-harmful.html"
->http://www.unicom.com/pw/reply-to-harmful.html</a>, in particular the
-"Principle of Least Damage" and "Can't Find My Way Back Home"
-sections.  From time to time, someone posts asking why we don't set
-the <tt>Reply-to</tt> header.  Sometimes that person will mention <a
-href="http://www.metasystema.net/essays/reply-to.mhtml"
->http://www.metasystema.net/essays/reply-to.mhtml</a>, which
-gives arguments in favor of modifying the <tt>Reply-to</tt> field.
-The list administrators are aware of both documents, and see that both
-sides of the argument have merits, but in the end have chosen not to
-modify the <tt>Reply-to</tt> headers.  Please don't resurrect the
-topic.</p>
-
-</div>
-
-<div class="h3" id="fresh-post" title="fresh-post">
-<h3>Making a Fresh Post</h3>
-
-<p>Don't start a new thread (subject) by replying to an existing
-post.  Instead, start a fresh mail, even if that means you have to
-write out the list address by
-hand.  If you reply to an existing post, your mailreader may include
-metadata that marks your post as a followup in that thread.  Changing
-the <tt>Subject</tt> header is not enough to prevent this!  Many
-mailreaders will still preserve enough metadata to put your post in
-the wrong thread.  If this happens, not only will some people not see
-your post (because they're ignoring that thread), but people who are
-reading the thread will waste their time with your off-topic post.
-The safest way to avoid this is to never use "reply" to start a new
-topic.</p>
-
-<p>(The root of the problem is really that some mail interfaces do
-not indicate that the message generated by the "Reply" function is
-different from a fresh message.  If you use such a program, consider
-submitting an enhancement request or a patch to its developers to make
-it show a distinction.)</p>
-
-</div>
-
-<div class="h3" id="rethreading" title="rethreading">
-<h3>Re-threading</h3>
-
-<p>If you do need to change the <tt>Subject</tt> header while
-preserving the thread (perhaps because the thread has wandered into
-some other topic), do it by making a post under the new subject with
-the old subject in parenthesis, like this:</p>
-
-<pre>
-   Blue asparagus
-     |
-     |_ Re: Blue asparagus
-         |
-         |_ Yellow elephants (was: Re: Blue asparagus)    <i>&lt;-- ### switch
###</i>
-            |
-            |_ Re: Yellow elephants
-</pre>
-
-</div>
-
-<div class="h3" id="top-posting" title="top-posting">
-<h3>Top-Posting</h3>
-
-<p>Please don't reflexively chide people for top-posting.
-"Top-posting" is the practice of putting the response text above the
-quoted text, instead of interleaved with it or below it.  Usually, the
-quoted text provides essential context for understanding the response,
-and so top-posting is a hindrance.  Sometimes, people top-post when it
-would have been better to inter-post or bottom-post, and others chide
-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&nbsp;&mdash;&nbsp;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>
-
-<p>If you came here looking for advice on how to quote, instead of
-advice on how to not flame people for their bad quoting habits, see <a
-href="http://www.netmeister.org/news/learn2quote.html"
->http://www.netmeister.org/news/learn2quote.html</a> (Deutsch:
-<a href="http://learn.to/quote">http://learn.to/quote</a>).</p>
-
-</div>
-
-</div>
-
-
-<div class="h3" id="patches" title="patches">
-<h3>Sending patches:</h3>
-
-<p>See
-<a href="hacking.html#patches">here</a> for advice on how to send in a
-patch.  Note that you can send in a patch to modify these web pages as
-well as to modify code; the web pages' repository URL is
-<a href="http://svn.collab.net/repos/svn/trunk/www/"
->http://svn.collab.net/repos/svn/trunk/www/</a>.</p>
-
-</div>
-
-
-<div class="h3" id="encodings" title="encodings">
-<h3>Languages and encodings:</h3>
-
-<p>Please use ASCII or ISO-8859 text if possible.  Don't post HTML
-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&nbsp;&mdash;&nbsp;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:
-   
-          Content-Type: text/plain; charset=iso-8859-1
-          Content-Type: text/plain; charset=iso-8859-15
-   
-        and
-   
-          Content-Transfer-Encoding: 8bit
-          Content-Transfer-Encoding: quoted-printable
-   -->
-
-</div>
-</div>
 </div>
 </body>
 </html>



Mime
View raw message