docs/130039: [patch] Add extra detail to the problem-reports article

[Gavin Atkinson]

>Number:         130039
>Category:       docs
>Synopsis:       [patch] Add extra detail to the problem-reports article
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Mon Dec 29 22:40:01 UTC 2008
>Closed-Date:
>Last-Modified:
>Originator:     Gavin Atkinson
>Release:        FreeBSD 7.1-PRERELEASE i386
>Organization:
FreeBSD
>Environment:
System: FreeBSD freefall.freebsd.org 7.1-PRERELEASE FreeBSD 7.1-PRERELEASE #36: Mon Dec 29 15:15:30 UTC 2008 simon at freefall.freebsd.org:/usr/src/sys/i386/compile/FREEFALL i386

>Description:
	Add some extra details to the problem-reports article.
Note that there is a single "whitespace" fix (moving a </listitem> tag)
in the patch as I've touched the line immediately preceding it.
Patch is also at http://people.freebsd.org/~gavin/my-prs/pr-article.diff

>How-To-Repeat:
	N/A
>Fix:

--- pr-article.diff begins here ---
Index: doc/en_US.ISO8859-1/articles/problem-reports/article.sgml
===================================================================
RCS file: /home/dcvs/doc/en_US.ISO8859-1/articles/problem-reports/article.sgml,v
retrieving revision 1.60
diff -u -r1.60 article.sgml
--- doc/en_US.ISO8859-1/articles/problem-reports/article.sgml	13 Jul 2008 14:37:24 -0000	1.60
+++ doc/en_US.ISO8859-1/articles/problem-reports/article.sgml	26 Dec 2008 19:55:17 -0000
@@ -390,6 +390,17 @@
 	    </listitem>
 
 	    <listitem>
+	      <para>If the problem can be reproduced easily, include
+		information that will help a developer to reproduce it
+		themselves.  If a problem can be demonstrated with
+		specific input then include an example of that input if
+		possible, and include both the actual and the expected
+		output.  If this data is large or cannot be made public,
+		then do try to create a minimal file that exibits the
+		same issue and that can be included within the PR.</para>
+	    </listitem>
+
+	    <listitem>
 	      <para>If this is a kernel problem, then be prepared to
 		supply the following information.  (You do not
 		have to include these by default, which only tends to
@@ -408,7 +419,14 @@
 		    sense of that option</para>
 		</listitem>
 		<listitem>
-		  <para>a backtrace, if one was generated</para>
+		  <para>the full text of any backtrace, panic or other console
+		    output, or entries in <filename>/var/log/messages</filename>,
+		    if any were generated</para>
+		</listitem>
+		<listitem>
+		  <para>the output of <command>pciconf -l</command> and
+		    relevant parts of your <command>dmesg</command> output if
+		    your problem relates to a specific piece of hardware</para>
 		</listitem>
 		<listitem>
 		  <para>the fact that you have read
@@ -471,7 +489,17 @@
 	    minute or two to use the web-based search engine at
 	    <ulink url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query"></ulink>.
 	    (Of course, everyone is guilty of forgetting to do this
-	    now and then.)</para> </listitem>
+	    now and then.)</para>
+	</listitem>
+
+	<listitem>
+	  <para><emphasis>Report only one issue per Problem
+	    Report.</emphasis> Avoid including two or more problems
+	    within the same report unless they are related.  When
+	    submitting patches, avoid adding multiple features or
+	    fixing multiple bugs in the same PR unless they are closely
+	    related—such PRs often take longer to resolve.</para>
+	</listitem>
 
 	<listitem>
 	  <para><emphasis>Avoid controversial requests.</emphasis>
--- pr-article.diff ends here ---


>Release-Note:
>Audit-Trail:
>Unformatted: