[PATCH 9/9] faq: general: add bug reporting FAQ

[Brian Foster]

On Monday 08 August 2011 21:37:19 Brian Norris wrote:
> It's surprising to note that we do not have a general "how to send a bug
> report" FAQ. This patch provides a starting point and (most importantly)
> directs UBI/UBIFS users to the appropriate bug reporting information.
> 
> Signed-off-by: Brian Norris <computersforpeace at gmail.com>
> ---
>  faq/general.xml |   54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  mail.xml        |    4 +++-
>  2 files changed, 57 insertions(+), 1 deletions(-)
> 
> diff --git a/faq/general.xml b/faq/general.xml
>[ ... ]
> +<H2>How do I report bugs?</H2>
> +</A>
> +
> +<P>
> +First, you need to figure out what you're reporting a bug against. This website
> +(and its accompanying <A HREF="../mail.html">mailing list</A>) supports several
> +related aspects of Linux, from the MTD kernel subsystem to its user-space
> +utilities, including the generic MTD and NAND interface layers, several MTD
> +hardware drivers, the UBI volume management system, several flash filesystems
> +(e.g., JFFS2, UBIFS), and the user-space MTD utils. People on the mailing list
> +will often support the YAFFS/YAFFS2 filesystems; however, YAFFS has its own
> +dedicated <A HREF="http://www.yaffs.net/">website</A> and
> +<A HREF="http://stoneboat.aleph1.co.uk/cgi-bin/mailman/listinfo/yaffs">mailing
> +list</A>, and its code is kept out of tree.

 A pedantic point that perhaps doesn't matter, but....
 Not quite sure what is meant by “kept out of tree”?
 Two interpertations I can think of:  YAFFS(2) is not
 in the UBI(FS) trees;  and/or  YAFFS(2) is not in the
 Linux kernel tree (albeit it is in the Android tree).

> +</P>
> +
> +<P>
> +Now, bug reports for any of the above areas are more than welcome on the

 “Any”?  Including YAFFS(2)?

 _Assuming_ YAFFS(2) wasn't meant to be included
 in the “any”, then I suggest moving the above
 YAFFS(2) remarks  — which are useful —  to later,
 perhaps after the other-FAQs list (below)?
 This resolves the pedantic confusion over “any”,
 and also takes what is basically an aside out of
 the main flow of text / information.

> +<A HREF="../mail.html">MTD mailing list</A>, provided you include sufficient
> +information for reproducing and debugging your problem. This means:
> +</P>
> +
> +<UL>
> +	<LI>include all kernel 'oopses', stack traces, debug messages, or
> +	relevant logs along with a clear description of the problem you're
> +	having, what system(s) are affected, and anything else you think might
> +	help understand your issue;</LI>
> +
> +	<LI>include information about flash parameters found from
> +	"<CODE>mtdinfo -a</CODE>" (or the less useful info from
> +	"<CODE>cat /proc/mtd</CODE>");</LI>

 I always suggest using ‘&nbsp;’ for spaces in
 inline  <code>⋯</code>  to prevent (what can be)
 horribly confusing inappropriate linebreaks.

 Thanks for addressing the how-to-report-bugs issue.
cheers!
	-blf-

>[ ... ]

-- 
Brian FOSTER
Principal MTS, Software
Maxim Integrated Products (Microcontroller BU), formerly Innova Card
Web    : http://www.maxim-ic.com/