www/mailing-list-guidelines.html - subversion - Git at Google

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml">
 <head>
 <style type="text/css"> /* <![CDATA[ */
   @import "branding/css/tigris.css";
   @import "branding/css/inst.css";
   /* ]]> */</style>
 <link rel="stylesheet" type="text/css" media="print"
   href="branding/css/print.css"/>
 <script type="text/javascript" src="branding/scripts/tigris.js"></script>
 <title>Guidelines for Posting to the Subversion Mailing Lists</title>
 </head>

 <body>
 <div class="app">

 <h1 style="text-align: center"
 >Guidelines for Posting to the Subversion Mailing Lists</h1>

 <p>This document is based on years of experience with the Subversion
 mailing lists, and specifically 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 the
 users@subversion.tigris.org or dev@subversion.tigris.org mailing
 lists, your post is much more likely to be read and answered.</p>


 <div class="h2" id="where" title="where">
 <h2>Where to post:</h2>

 <p>Post to <a href="mailto:users@subversion.tigris.org"
 >users@subversion.tigris.org</a> if you have a question about
 Subversion, or if you think you've found a bug (developers read the
 users list too, so they'll see your bug report).  If you want to
 discuss Subversion development, or post a <a href="#patches">code
 contribution</a>, then mail <a
 href="mailto:dev@subversion.tigris.org">dev@subversion.tigris.org</a>.</p>

 <p>When in doubt, mail users@, not dev@.</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 necessarily make the question on-topic
 for dev@.  (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.)</p>

 <div class="h3" id="bug-reports" title="bug-reports">
 <h3>Reporting a bug:</h3>

 <p>Please report bugs on the users@ list first, to get confirmation
 that what you found actually <em>is</em> a bug, then post to dev@ with
 a full report.  You should allocate some time for this: writing a
 useful bug report generally takes at least fifteen minutes, and
 sometimes a half-hour or even more if the reproduction recipe is
 complicated.  See the <a href="bugs.html">bug report guidelines</a>
 for instructions on how to write a good bug report.</p>

 <p><strong><em>WE REALLY MEAN THAT :-).</em></strong> We get too many
 useless bug reports, just saying "It didn't work" without providing
 any details (such as what version of Subversion was being used on both
 the client and server sides, what behavior the user expected,
 transcripts of the exact command and the exact output, etc).  If you
 haven't read the <a href="bugs.html">bug report guidelines</a>, please
 read them now.  Here's that link again: <a href="bugs.html">bug report
 guidelines</a>.</p>

 </div>

 </div>

 <div class="h2" id="when" title="when">
 <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 class="h3" id="look-first" title="look-first">
 <h3>Look before you post:</h3>
 <a name="archives"></a> <!-- for compatibility with old link -->

 <p>There are many sources of information about Subversion on the
 Internet.  While the list below isn't complete, most questions asked
 on users@ can be answered by pointing the asker to one of these:</p>

 <ul>
 <li>The <a href="http://subversion.tigris.org/faq.html">FAQ</a>.</li>

 <li>The book <a href="http://svnbook.red-bean.com/"
     >Version Control With Subversion</a> (full content available
     online).</li>

 <li>The
     <a href="http://subversion.tigris.org/servlets/SearchList?listName=users"
     >users@ mailing list archives</a>.</li>

 <li>The
     <a href="http://subversion.tigris.org/servlets/SearchList?listName=dev"
     >dev@ mailing list archives</a>.</li>

 <li>An <a href="http://svn.haxx.se/users">alternate users@
     archive</a>, with a somewhat different interface.</li>

 <li>An <a href="http://svn.haxx.se/dev">alternate dev@
     archive</a>, with a somewhat different interface.</li>

 <li>The <a href="http://subversion.tigris.org/links.html">
     Subversion-related links</a> page.</li>

 </ul>

 </div>

 </div>


 <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>

 <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 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>

 <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="h2" id="patches" title="patches">
 <h2>Sending patches:</h2>

 <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="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>
 </div>
 </body>
 </html>
	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
	<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
	<style type="text/css"> /* <![CDATA[ */
	@import "branding/css/tigris.css";
	@import "branding/css/inst.css";
	/* ]]> */</style>
	<link rel="stylesheet" type="text/css" media="print"
	href="branding/css/print.css"/>
	<script type="text/javascript" src="branding/scripts/tigris.js"></script>
	<title>Guidelines for Posting to the Subversion Mailing Lists</title>
	</head>

	<body>
	<div class="app">

	<h1 style="text-align: center"
	>Guidelines for Posting to the Subversion Mailing Lists</h1>

	<p>This document is based on years of experience with the Subversion
	mailing lists, and specifically 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
	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>

	<p>If you follow these conventions when posting to the
	users@subversion.tigris.org or dev@subversion.tigris.org mailing
	lists, your post is much more likely to be read and answered.</p>


	<div class="h2" id="where" title="where">
	<h2>Where to post:</h2>

	<p>Post to <a href="mailto:users@subversion.tigris.org"
	>users@subversion.tigris.org</a> if you have a question about
	Subversion, or if you think you've found a bug (developers read the
	users list too, so they'll see your bug report). If you want to
	discuss Subversion development, or post a <a href="#patches">code
	contribution</a>, then mail <a
	href="mailto:dev@subversion.tigris.org">dev@subversion.tigris.org</a>.</p>

	<p>When in doubt, mail users@, not dev@.</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 necessarily make the question on-topic
	for dev@. (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.)</p>

	<div class="h3" id="bug-reports" title="bug-reports">
	<h3>Reporting a bug:</h3>

	<p>Please report bugs on the users@ list first, to get confirmation
	that what you found actually <em>is</em> a bug, then post to dev@ with
	a full report. You should allocate some time for this: writing a
	useful bug report generally takes at least fifteen minutes, and
	sometimes a half-hour or even more if the reproduction recipe is
	complicated. See the <a href="bugs.html">bug report guidelines</a>
	for instructions on how to write a good bug report.</p>

	<p><strong><em>WE REALLY MEAN THAT :-).</em></strong> We get too many
	useless bug reports, just saying "It didn't work" without providing
	any details (such as what version of Subversion was being used on both
	the client and server sides, what behavior the user expected,
	transcripts of the exact command and the exact output, etc). If you
	haven't read the <a href="bugs.html">bug report guidelines</a>, please
	read them now. Here's that link again: <a href="bugs.html">bug report
	guidelines</a>.</p>

	</div>

	</div>

	<div class="h2" id="when" title="when">
	<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 class="h3" id="look-first" title="look-first">
	<h3>Look before you post:</h3>
	<a name="archives"></a> <!-- for compatibility with old link -->

	<p>There are many sources of information about Subversion on the
	Internet. While the list below isn't complete, most questions asked
	on users@ can be answered by pointing the asker to one of these:</p>

	<ul>
	<li>The <a href="http://subversion.tigris.org/faq.html">FAQ</a>.</li>

	<li>The book <a href="http://svnbook.red-bean.com/"
	>Version Control With Subversion</a> (full content available
	online).</li>

	<li>The
	<a href="http://subversion.tigris.org/servlets/SearchList?listName=users"
	>users@ mailing list archives</a>.</li>

	<li>The
	<a href="http://subversion.tigris.org/servlets/SearchList?listName=dev"
	>dev@ mailing list archives</a>.</li>

	<li>An <a href="http://svn.haxx.se/users">alternate users@
	archive</a>, with a somewhat different interface.</li>

	<li>An <a href="http://svn.haxx.se/dev">alternate dev@
	archive</a>, with a somewhat different interface.</li>

	<li>The <a href="http://subversion.tigris.org/links.html">
	Subversion-related links</a> page.</li>

	</ul>

	</div>

	</div>


	<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>

	<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 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>

	<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><-- ### 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 — 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="h2" id="patches" title="patches">
	<h2>Sending patches:</h2>

	<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="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 — 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>
	</body>
	</html>