From gavin@FreeBSD.org  Mon Dec 29 22:30:14 2008
Return-Path: <gavin@FreeBSD.org>
Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34])
	by hub.freebsd.org (Postfix) with ESMTP id B87A71065678
	for <FreeBSD-gnats-submit@freebsd.org>; Mon, 29 Dec 2008 22:30:14 +0000 (UTC)
	(envelope-from gavin@FreeBSD.org)
Received: from freefall.freebsd.org (freefall.freebsd.org [IPv6:2001:4f8:fff6::28])
	by mx1.freebsd.org (Postfix) with ESMTP id A54408FC08
	for <FreeBSD-gnats-submit@freebsd.org>; Mon, 29 Dec 2008 22:30:14 +0000 (UTC)
	(envelope-from gavin@FreeBSD.org)
Received: from freefall.freebsd.org (gavin@localhost [127.0.0.1])
	by freefall.freebsd.org (8.14.3/8.14.3) with ESMTP id mBTMUEo0012017
	for <FreeBSD-gnats-submit@freebsd.org>; Mon, 29 Dec 2008 22:30:14 GMT
	(envelope-from gavin@freefall.freebsd.org)
Received: (from gavin@localhost)
	by freefall.freebsd.org (8.14.3/8.14.3/Submit) id mBTMUEx2012008;
	Mon, 29 Dec 2008 22:30:14 GMT
	(envelope-from gavin)
Message-Id: <200812292230.mBTMUEx2012008@freefall.freebsd.org>
Date: Mon, 29 Dec 2008 22:30:14 GMT
From: Gavin Atkinson <gavin@freebsd.org>
Reply-To: Gavin Atkinson <gavin@freebsd.org>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: [patch] Add extra detail to the problem-reports article
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>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:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Mon Dec 29 22:40:01 UTC 2008
>Closed-Date:    Tue Dec 30 08:25:05 UTC 2008
>Last-Modified:  Tue Dec 30 08:30:01 UTC 2008
>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@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&mdash;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:
State-Changed-From-To: open->closed 
State-Changed-By: remko 
State-Changed-When: Tue Dec 30 08:25:04 UTC 2008 
State-Changed-Why:  
Committed. Thanks! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=130039 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/130039: commit references a PR
Date: Tue, 30 Dec 2008 08:25:09 +0000 (UTC)

 remko       2008-12-30 08:24:55 UTC
 
   FreeBSD doc repository
 
   Modified files:
     en_US.ISO8859-1/articles/problem-reports article.sgml 
   Log:
   Add some extra details to the article.
   
   One whitespace move, because area was touched by
   submitter.
   
   PR:             130039
   Submitted by:   gavin
   
   Revision  Changes    Path
   1.61      +30 -2     doc/en_US.ISO8859-1/articles/problem-reports/article.sgml
 _______________________________________________
 cvs-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/cvs-all
 To unsubscribe, send any mail to "cvs-all-unsubscribe@freebsd.org"
 
>Unformatted:
