path: root/en_US.ISO8859-1/articles/problem-reports/article.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
	"http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">
<article xmlns="http://docbook.org/ns/docbook"
  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
  xml:lang="en">

  <info>
    <title>Writing &os; Problem Reports</title>

    <legalnotice xml:id="trademarks" role="trademarks">
      &tm-attrib.freebsd;
      &tm-attrib.ibm;
      &tm-attrib.intel;
      &tm-attrib.sparc;
      &tm-attrib.sun;
      &tm-attrib.general;
    </legalnotice>

    <pubdate>$FreeBSD$</pubdate>

    <releaseinfo>$FreeBSD$</releaseinfo>

    <abstract>
      <para>This article describes how to best formulate and submit a
	problem report to the &os; Project.</para>
    </abstract>

    <authorgroup>
      <author>
	<personname>
	  <firstname>Dag-Erling</firstname>
	  <surname>Sm&oslash;rgrav</surname>
	</personname>
	<contrib>Contributed by </contrib>
      </author>

      <author>
	<personname>
	  <firstname>Mark</firstname>
	  <surname>Linimon</surname>
	</personname>
      </author>
    </authorgroup>
  </info>

  <indexterm><primary>problem reports</primary></indexterm>

  <section xml:id="pr-intro">
    <title>Introduction</title>

    <para>One of the most frustrating experiences one can have as a
      software user is to submit a problem report only to have it
      summarily closed with a terse and unhelpful explanation like
      <quote>not a bug</quote> or <quote>bogus PR</quote>.  Similarly,
      one of the most frustrating experiences as a software developer
      is to be flooded with problem reports that are not really
      problem reports but requests for support, or that contain little
      or no information about what the problem is and how to reproduce
      it.</para>

    <para>This document attempts to describe how to write good problem
      reports.  What, one asks, is a good problem report?  Well, to go
      straight to the bottom line, a good problem report is one that
      can be analyzed and dealt with swiftly, to the mutual
      satisfaction of both user and developer.</para>

    <para>Although the primary focus of this article is on &os;
      problem reports, most of it should apply quite well to other
      software projects.</para>

    <para>Note that this article is organized thematically, not
      chronologically.  Read the entire document
      before submitting a problem report, rather than treating it as a
      step-by-step tutorial.</para>
  </section>

  <section xml:id="pr-when">
    <title>When to Submit a Problem Report</title>

    <para>There are many types of problems, and not all of them should
      engender a problem report.  Of course, nobody is perfect, and
      there will be times when what seems to be a bug in a program is,
      in fact, a misunderstanding of the syntax for a command or a
      typographical error in a configuration file (though that in
      itself may sometimes be indicative of poor documentation or poor
      error handling in the application).  There are still many cases
      where submitting a problem report is clearly
      <emphasis>not</emphasis> the right course of action, and will
      only serve to frustrate both the submitter and the developers.
      Conversely, there are cases where it might be appropriate to
      submit a problem report about something else than a bug&mdash;an
      enhancement or a new feature, for instance.</para>

    <para>So how does one determine what is a bug and what is not?  As
      a simple rule of thumb, the problem is <emphasis>not</emphasis>
      a bug if it can be expressed as a question (usually of the form
      <quote>How do I do X?</quote> or <quote>Where can I find
      Y?</quote>).  It is not always quite so black and white, but the
      question rule covers a large majority of cases.  When looking
      for an answer, consider posing the question to the
      &a.questions;.</para>

    <para>Some cases where it may be appropriate to submit a problem
      report about something that is not a bug are:</para>

    <itemizedlist>
      <listitem>
	<para>Notification of updates to externally maintained
	  software (such as ports or software in the contrib/
	  directory).</para>

	<para>For unmaintained ports (<varname>MAINTAINER</varname>
	  contains <literal>ports@FreeBSD.org</literal>), such update
	  notifications might get picked up by an interested
	  committer, or you might be asked to provide a patch to
	  update the port; providing it upfront will greatly improve
	  your chances that the port will get updated in a timely
	  manner.</para>

	<para>If the port is maintained, PRs announcing new upstream
	  releases are usually not very useful since they generate
	  supplementary work for the committers, and the maintainer
	  likely knows already there is a new version, they have
	  probably worked with the developers on it, they are probably
	  testing to see there is no regression, etc.</para>

	<para>In either case, following the process described in <link
	    xlink:href="&url.books.porters-handbook;/port-upgrading.html">Porter's
	    Handbook</link> will yield the best results.  (You might
	  also wish to read <link
	    xlink:href="&url.articles.contributing-ports;/article.html">Contributing
	    to the FreeBSD Ports Collection</link>.)</para>
      </listitem>
    </itemizedlist>

    <para>A bug that cannot be reproduced can rarely be fixed.  If the
      bug only occurred once and you can not reproduce it, and it does
      not seem to happen to anybody else, chances are none of the
      developers will be able to reproduce it or figure out what is
      wrong.  That does not mean it did not happen, but it does mean
      that the chances of your problem report ever leading to a bug
      fix are very slim.  To make matters worse, often these kinds of
      bugs are actually caused by failing hard drives or overheating
      processors &mdash; you should always try to rule out these
      causes, whenever possible, before submitting a PR.</para>

    <para>Next, to decide to whom you should file your problem report,
      you need to understand that the software that makes up &os; is
      composed of several different elements:</para>

    <itemizedlist>
      <listitem>
	<para>Code in the base system that is written and maintained
	  by &os; contributors, such as the kernel, the C library, and
	  the device drivers (categorized as <literal>kern</literal>);
	  the binary utilities (<literal>bin</literal>); the manual
	  pages and documentation (<literal>docs</literal>); and the
	  web pages (<literal>www</literal>).  All bugs in these areas
	  should be reported to the &os; developers.</para>
      </listitem>

      <listitem>
	<para>Code in the base system that is written and maintained
	  by others, and imported into &os; and adapted.  Examples
	  include &man.clang.1;, and
	  &man.sendmail.8;.  Most bugs in these areas should be
	  reported to the &os; developers; but in some cases they may
	  need to be reported to the original authors instead if the
	  problems are not &os;-specific.</para>
      </listitem>

      <listitem>
	<para>Individual applications that are not in the base system
	  but are instead part of the &os; Ports Collection (category
	  <literal>ports</literal>).  Most of these applications are
	  not written by &os; developers; what &os; provides is merely
	  a framework for installing the application.  Therefore, only
	  report a problem to the &os; developers when the problem is
	  believed to be &os;-specific; otherwise, report it to the
	  authors of the software.</para>
      </listitem>
    </itemizedlist>

    <para>Then, ascertain whether the problem is timely.  There are
      few things that will annoy a developer more than receiving a
      problem report about a bug she has already fixed.</para>

    <para>If the problem is in the base system, first read the FAQ
      section on <link
	xlink:href="&url.books.faq;/introduction.html#LATEST-VERSION">&os;
	versions</link>, if you are not already familiar with the
      topic.  It is not possible for &os; to fix problems in anything
      other than certain recent branches of the base system, so filing
      a bug report about an older version will probably only result in
      a developer advising you to upgrade to a supported version to
      see if the problem still recurs.  The Security Officer team
      maintains the
      <link xlink:href="&url.base;/security/">list of supported
	versions</link>.</para>

    <para>If the problem is in a port, note that you must first
      upgrade to the latest version of the Ports Collection and see if
      the problem still applies.  Due to the rapid pace of changes in
      these applications, it is infeasible for &os; to support
      anything other than the absolute latest versions, and problems
      with older version of applications simply cannot be
      fixed.</para>
  </section>

  <section xml:id="pr-prep">
    <title>Preparations</title>

    <para>A good rule to follow is to always do a background search
      before submitting a problem report.  Maybe the problem has
      already been reported; maybe it is being discussed on the
      mailing lists, or recently was; it may even already be fixed in
      a newer version than what you are running.  You should therefore
      check all the obvious places before submitting your problem
      report.  For &os;, this means:</para>

    <itemizedlist>
      <listitem>
	<para>The &os; <link
	    xlink:href="&url.books.faq;/index.html">Frequently Asked
	    Questions</link> (FAQ) list.
	  The FAQ attempts to provide answers for a wide range of
	  questions, such as those concerning
	  <link xlink:href="&url.books.faq;/hardware.html">hardware
	    compatibility</link>,
	  <link xlink:href="&url.books.faq;/applications.html">user
	    applications</link>, and
	  <link xlink:href="&url.books.faq;/kernelconfig.html">kernel
	    configuration</link>.</para>
      </listitem>

      <listitem>
	<para>The <link
	    xlink:href="&url.books.handbook;/eresources.html#ERESOURCES-MAIL">mailing
	    lists</link>&mdash;if you are not subscribed, use <link
	    xlink:href="http://www.FreeBSD.org/search/search.html#mailinglists">the
	    searchable archives</link> on the &os; web site.  If the
	  problem has not been discussed on the lists, you might try
	  posting a message about it and waiting a few days to see if
	  someone can spot something that has been overlooked.</para>
      </listitem>

      <listitem>
	<para>Optionally, the entire web&mdash;use your favorite
	  search engine to locate any references to the problem.  You
	  may even get hits from archived mailing lists or newsgroups
	  you did not know of or had not thought to search
	  through.</para>
      </listitem>

      <listitem>
	<para>Next, the searchable <link
	    xlink:href="https://bugs.freebsd.org/bugzilla/query.cgi">&os;
	    PR database</link> (Bugzilla).  Unless the problem is recent
	  or obscure, there is a fair chance it has already been
	  reported.</para>
      </listitem>

      <listitem>
	<para>Most importantly, attempt to see if existing
	  documentation in the source base addresses your
	  problem.</para>

	<para>For the base &os; code, you should carefully study the
	  contents of <filename>/usr/src/UPDATING</filename> on your
	  system or the latest version at <uri
	    xlink:href="http://svnweb.freebsd.org/base/head/UPDATING?view=log">http://svnweb.freebsd.org/base/head/UPDATING?view=log</uri>.
	  (This is vital information if you are upgrading from one
	  version to another&mdash;especially if you are upgrading to
	  the &os.current; branch).</para>

	<para>However, if the problem is in something that was
	  installed as a part of the &os; Ports Collection, you should
	  refer to <filename>/usr/ports/UPDATING</filename> (for
	  individual ports) or <filename>/usr/ports/CHANGES</filename>
	  (for changes that affect the entire Ports Collection).  <uri
	    xlink:href="http://svnweb.freebsd.org/ports/head/UPDATING?view=log">http://svnweb.freebsd.org/ports/head/UPDATING?view=log</uri>
	  and <uri
	    xlink:href="http://svnweb.freebsd.org/ports/head/CHANGES?view=log">http://svnweb.freebsd.org/ports/head/CHANGES?view=log</uri>
	  are also available via svnweb.</para>
      </listitem>
    </itemizedlist>
  </section>

  <section xml:id="pr-writing">
    <title>Writing the Problem Report</title>

    <para>Now that you have decided that your issue merits a problem
      report, and that it is a &os; problem, it is time to write the
      actual problem report.  Before we get into the mechanics of the
      program used to generate and submit PRs, here are some tips and
      tricks to help make sure that your PR will be most
      effective.</para>

    <section xml:id="pr-writing-tips">
      <title>Tips and Tricks for Writing a Good Problem Report</title>

      <itemizedlist>
	<listitem>
	  <para><emphasis>Do not leave the <quote>Synopsis</quote>
	      line empty.</emphasis> The PRs go both onto a mailing
	    list that goes all over the world (where the
	    <quote>Synopsis</quote> is used for the
	    <literal>Subject:</literal> line), but also into a
	    database.  Anyone who comes along later and browses the
	    database by synopsis, and finds a PR with a blank subject
	    line, tends just to skip over it.  Remember that PRs stay
	    in this database until they are closed by someone; an
	    anonymous one will usually just disappear in the
	    noise.</para>
	</listitem>

	<listitem>
	  <para><emphasis>Avoid using a weak <quote>Synopsis</quote>
	      line.</emphasis>  You should not assume that anyone
	    reading your PR has any context for your submission, so
	    the more you provide, the better.  For instance, what part
	    of the system does the problem apply to?  Do you only see
	    the problem while installing, or while running?  To
	    illustrate, instead of
	    <literal>Synopsis: portupgrade is broken</literal>, see
	    how much more informative this seems:
	    <literal>Synopsis: port ports-mgmt/portupgrade coredumps
	      on -current</literal>.  (In the case of ports, it is
	    especially helpful to have both the category and portname
	    in the <quote>Synopsis</quote> line.)</para>
	</listitem>

	<listitem>
	  <para><emphasis>If you have a patch, say so.</emphasis>
	    A PR with a patch included is much more likely to be
	    looked at than one without.  If you are including one, put
	    the string <literal>[patch]</literal> (including the
	    brackets) at the beginning of the <quote>Synopsis</quote>.
	    (Although it is not mandatory to use that exact string, by
	    convention, that is the one that is used.)</para>
	</listitem>

	<listitem>
	  <para><emphasis>If you are a maintainer, say so.</emphasis>
	    If you are maintaining a part of the source code (for
	    instance, a port), you might consider adding the string
	    <literal>[maintainer update]</literal> (including the
	    brackets) at the beginning of your synopsis line, and you
	    definitely should set the <quote>Class</quote> of your PR
	    to <literal>maintainer-update</literal>.  This way any
	    committer that handles your PR will not have to
	    check.</para>
	</listitem>

	<listitem>
	  <para><emphasis>Be specific.</emphasis> The more information
	    you supply about what problem you are having, the better
	    your chance of getting a response.</para>

	  <itemizedlist>
	    <listitem>
	      <para>Include the version of &os; you are running (there
		is a place to put that, see below) and on which
		architecture.  You should include whether you are
		running from a release (e.g., from a
		<acronym>CD-ROM</acronym> or download), or from a
		system maintained by Subversion (and, if so, what
		revision number you are at).  If you are tracking the
		&os.current; branch, that is the very first thing
		someone will ask, because fixes (especially for
		high-profile problems) tend to get committed very
		quickly, and &os.current; users are expected to keep
		up.</para>
	    </listitem>

	    <listitem>
	      <para>Include which global options you have specified in
		your <filename>make.conf</filename>.  Note: specifying
		<literal>-O2</literal> and above to &man.gcc.1; is
		known to be buggy in many situations.  While the &os;
		developers will accept patches, they are generally
		unwilling to investigate such issues due to simple
		lack of time and volunteers, and may instead respond
		that this just is not supported.</para>
	    </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
		exhibits 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 fill up
		the database, but you should include excerpts that you
		think might be relevant):</para>

	      <itemizedlist>
		<listitem>
		  <para>your kernel configuration (including which
		    hardware devices you have installed)</para>
		</listitem>

		<listitem>
		  <para>whether or not you have debugging options
		    enabled (such as <literal>WITNESS</literal>), and
		    if so, whether the problem persists when you
		    change the sense of that option</para>
		</listitem>

		<listitem>
		  <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
		    <filename>src/UPDATING</filename> and that your
		    problem is not listed there (someone is guaranteed
		    to ask)</para>
		</listitem>

		<listitem>
		  <para>whether or not you can run any other kernel as
		    a fallback (this is to rule out hardware-related
		    issues such as failing disks and overheating CPUs,
		    which can masquerade as kernel problems)</para>
		</listitem>
	      </itemizedlist>
	    </listitem>

	    <listitem>
	      <para>If this is a ports problem, then be prepared to
		supply the following information.  (You do not
		have to include these by default, which only tends to
		fill up the database, but you should include excerpts
		that you think might be relevant):</para>

	      <itemizedlist>
		<listitem>
		  <para>which ports you have installed</para>
		</listitem>

		<listitem>
		  <para>any environment variables that override the
		    defaults in <filename>bsd.port.mk</filename>, such
		    as <varname>PORTSDIR</varname></para>
		</listitem>

		<listitem>
		  <para>the fact that you have read
		    <filename>ports/UPDATING</filename> and that your
		    problem is not listed there (someone is guaranteed
		    to ask)</para>
		</listitem>
	      </itemizedlist>
	    </listitem>
	  </itemizedlist>
	</listitem>

	<listitem>
	  <para><emphasis>Avoid vague requests for
	      features.</emphasis> PRs of the form
	    <quote>someone should really implement something that does
	      so-and-so</quote> are less likely to get results than
	    very specific requests.  Remember, the source is available
	    to everyone, so if you want a feature, the best way to
	    ensure it being included is to get to work!  Also consider
	    the fact that many things like this would make a better
	    topic for discussion on
	    <literal>freebsd-questions</literal> than an entry in the
	    PR database, as discussed above.</para>
	</listitem>

	<listitem>
	  <para><emphasis>Make sure no one else has already submitted
	      a similar PR.</emphasis> Although this has already been
	    mentioned above, it bears repeating here.  It only take a
	    minute or two to use the web-based search engine at <uri
	      xlink:href="https://bugs.freebsd.org/bugzilla/query.cgi">https://bugs.freebsd.org/bugzilla/query.cgi</uri>.
	    (Of course, everyone is guilty of forgetting to do this
	    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>
	    If your PR addresses an area that has been controversial
	    in the past, you should probably be prepared to not only
	    offer patches, but also justification for why the patches
	    are <quote>The Right Thing To Do</quote>.  As noted above,
	    a careful search of the mailing lists using the archives
	    at <uri
	      xlink:href="http://www.FreeBSD.org/search/search.html#mailinglists">http://www.FreeBSD.org/search/search.html#mailinglists</uri>
	    is always good preparation.</para>
	</listitem>

	<listitem>
	  <para><emphasis>Be polite.</emphasis> Almost anyone who
	    would potentially work on your PR is a volunteer.  No one
	    likes to be told that they have to do something when they
	    are already doing it for some motivation other than
	    monetary gain.  This is a good thing to keep in mind at
	    all times on Open Source projects.</para>
	</listitem>
      </itemizedlist>
    </section>

    <section xml:id="pr-writing-before-beginning">
      <title>Before Beginning</title>

      <para>Similar considerations apply to use of the
	<link xlink:href="https://bugs.freebsd.org/bugzilla/enter_bug.cgi"> web-based
	PR submission form</link>.  Be careful of cut-and-paste
	operations that might change whitespace or other text
	formatting.</para>

      <para>Finally, if the submission is lengthy, prepare the work
	offline so that nothing will be lost if there is a problem
	submitting it.</para>
    </section>

    <section xml:id="pr-writing-attaching-patches">
      <title>Attaching Patches or Files</title>

      <para>When attaching a patch, be sure to use
	<option>-u</option> with &man.diff.1;
	to create or unified diff
	and make sure to specify the exact SVN revision numbers of the
	files you modified so the developers who read your report will
	be able to apply them easily.  For problems with the kernel or
	the base utilities, a patch against &os.current; (the HEAD
	Subversion branch) is preferred since all new code should be
	applied and tested there first.  After appropriate or
	substantial testing has been done, the code will be
	merged/migrated to the &os.stable; branch.</para>

      <para>If you attach a patch inline, instead of as an attachment,
	note that the most common problem by far is the tendency of
	some email programs to render tabs as spaces, which will
	completely ruin anything intended to be part of a
	Makefile.</para>

      <para>Do not send patches as attachments using
	<command>Content-Transfer-Encoding:
	  quoted-printable</command>.  These will perform character
	escaping and the entire patch will be useless.</para>

      <para>Also note that while including small patches in a PR is
	generally all right&mdash;particularly when they fix the
	problem described in the PR&mdash;large patches and especially
	new code which may require substantial review before
	committing should be placed on a web or ftp server, and the
	URL should be included in the PR instead of the patch.
	Patches in email tend to get mangled,
	and the larger the patch, the harder it will be for
	interested parties to unmangle it.  Also, posting a patch on
	the web allows you to modify it without having to resubmit the
	entire patch in a followup to the original PR.  Finally, large
	patches simply increase the size of the database, since closed
	PRs are not actually deleted but instead kept and simply
	marked as complete.</para>

      <para>You should also take note that unless you explicitly
	specify otherwise in your PR or in the patch itself, any
	patches you submit will be assumed to be licensed under the
	same terms as the original file you modified.</para>
    </section>

    <section xml:id="pr-writing-filling-template">
      <title>Filling out the Template</title>

      <para>In the email template only, you will find the following
	single-line fields:</para>

      <itemizedlist>
	<listitem>
	  <para><emphasis>Submitter-Id:</emphasis> Do not change this.
	    The default value of <literal>current-users</literal> is
	    correct, even if you run &os.stable;.</para>
	</listitem>

	<listitem>
	  <para><emphasis>Confidential:</emphasis> This is prefilled
	    to <literal>no</literal>.   Changing it makes no sense as
	    there is no such thing as a confidential &os; problem
	    report&mdash;the PR database is distributed
	    worldwide.</para>
	</listitem>

	<listitem>
	  <para><emphasis>Severity:</emphasis> One of
	    <literal>non-critical</literal>,
	    <literal>serious</literal> or <literal>critical</literal>.
	    Do not overreact; refrain from labeling your problem
	    <literal>critical</literal> unless it really is (e.g.,
	    data corruption issues, serious regression from previous
	    functionality in -CURRENT) or <literal>serious</literal>
	    unless it is something that will affect many users (kernel
	    panics or freezes; problems with particular device drivers
	    or system utilities).  &os; developers will not
	    necessarily work on your problem faster if you inflate its
	    importance since there are so many other people who have
	    done exactly that &mdash; in fact, some developers pay
	    little attention to this field because of this.</para>
	</listitem>

	<listitem>
	  <para><emphasis>Priority:</emphasis> This field indicates
	    how widespread the effects of this bug is likely to
	    be.</para>
	</listitem>


      </itemizedlist>

      <para>The next section describes fields that are common to both
	the email interface and the
	<link xlink:href="https://bugs.freebsd.org/bugzilla/enter_bug.cgi">web
	  interface</link>:</para>

      <itemizedlist>
	<listitem>
	  <para><emphasis>Originator:</emphasis> Please specify your
	    real name, optionally followed by your email address in
	    angle brackets.  In the email interface, this is normally
	    prefilled with the <literal>gecos</literal> field of the
	    currently logged-in user.</para>

	  <note>
	    <para>The email address you use will become public
	      information and may become available to spammers.  You
	      should either have spam handling procedures in place, or
	      use a temporary email account.  However, please note
	      that if you do not use a valid email account at all, we
	      will not be able to ask you questions about your
	      PR.</para>
	  </note>
	</listitem>

	<listitem>
	  <para><emphasis>Organization:</emphasis> Whatever you feel
	    like.  This field is not used for anything
	    significant.</para>
	</listitem>

	<listitem>
	  <para><emphasis>Synopsis:</emphasis> Fill this out with a
	    short and accurate description of the problem.  The
	    synopsis is used as the subject of the problem report
	    email, and is used in problem report listings and
	    summaries; problem reports with obscure synopses tend to
	    get ignored.</para>

	  <para>As noted above, if your problem report includes a
	    patch, please have the synopsis start with
	    <literal>[patch]</literal> (including the brackets); if
	    this is a ports PR and you are the maintainer, you may
	    consider adding <literal>[maintainer update]</literal>
	    (including the brackets) and set the <quote>Class</quote>
	    of your PR to <literal>maintainer-update</literal>.</para>
	</listitem>

	<listitem>
	  <para><emphasis>Category:</emphasis> Choose an appropriate
	    category.</para>

	  <para>The first thing you need to do is to decide what part
	    of the system your problem lies in.  Remember, &os; is a
	    complete operating system, which installs both a kernel,
	    the standard libraries, many peripheral drivers, and a
	    large number of utilities (the
	    <quote>base system</quote>).  However, there are thousands
	    of additional applications in the Ports Collection.
	    You'll first need to decide if the problem is in the base
	    system or something installed via the Ports
	    Collection.</para>

	  <para>Here is a description of the major categories:</para>

	  <itemizedlist>
	    <listitem>
	      <para>If a problem is with the kernel, the libraries
		(such as standard C library <literal>libc</literal>),
		or a peripheral driver in the base system, in general
		you will use the <literal>kern</literal> category.
		(There are a few exceptions; see below).  In general
		these are things that are described in section 2, 3,
		or 4 of the manual pages.</para>
	    </listitem>

	    <listitem>
	      <para>If a problem is with a binary program such as
		&man.sh.1; or &man.mount.8;, you will first need to
		determine whether these programs are in the base
		system or were added via the Ports Collection.  If you
		are unsure, you can do <command>whereis
		  <replaceable>programname</replaceable></command>.
		&os;'s convention for the Ports Collection is to
		install everything underneath
		<filename class="directory">/usr/local</filename>,
		although this can be overridden by a system
		administrator.  For these, you will use the
		<literal>ports</literal> category (yes, even if the
		port's category is <literal>www</literal>; see below).
		If the location is
		<filename class="directory">/bin</filename>,
		<filename class="directory">/usr/bin</filename>,
		<filename class="directory">/sbin</filename>, or
		<filename class="directory">/usr/sbin</filename>, it
		is part of the base system, and you should use the
		<literal>bin</literal> category.  (A few programs,
		such as &man.gcc.1;, actually use the
		<literal>gnu</literal> category, but do not worry
		about that for now.)  These are all things that are
		described in section 1 or 8 of the manual
		pages.</para>
	    </listitem>

	    <listitem>
	      <para>If you believe that the error is in the startup
		<literal>(rc)</literal> scripts, or in some kind of
		other non-executable configuration file, then the
		right category is <literal>conf</literal>
		(configuration).  These are things that are described
		in section 5 of the manual pages.</para>
	    </listitem>

	    <listitem>
	      <para>If you have found a problem in the documentation
		set (articles, books, man pages), the correct choice
		is <literal>docs</literal>.</para>
	    </listitem>

	    <listitem>
	      <para>If you are having a problem with the <link
		  xlink:href="http://www.FreeBSD.org">FreeBSD web
		pages</link>, the proper choice is
		<literal>www</literal>.</para>

	      <note>
		<para>if you are having a problem with something from
		  a port named
		  <literal>www/<replaceable>someportname</replaceable></literal>,
		  this nevertheless goes in the
		  <literal>ports</literal> category.</para>
	      </note>
	    </listitem>
	  </itemizedlist>

	  <para>There are a few more specialized categories.</para>

	  <itemizedlist>
	    <listitem>
	      <para>If the problem would otherwise be filed in
		<literal>kern</literal> but has to do with the USB
		subsystem, the correct choice is
		<literal>usb</literal>.</para>
	    </listitem>

	    <listitem>
	      <para>If the problem would otherwise be filed in
		<literal>kern</literal> but has to do with the
		threading libraries, the correct choice is
		<literal>threads</literal>.</para>
	    </listitem>

	    <listitem>
	      <para>If the problem would otherwise be in the base
		system, but has to do with our adherence to standards
		such as &posix;, the correct choice is
		<literal>standards</literal>.</para>
	    </listitem>

	    <listitem>
	      <para>If the problem has to do with errors internal to a
		&java.virtual.machine; (&jvm;), even though &java; was
		installed from the Ports Collection, you should select
		the <literal>java</literal> category.  More general
		problems with &java; ports still go under
		<literal>ports</literal>.</para>
	    </listitem>
	  </itemizedlist>

	  <para>This leaves everything else.</para>

	  <itemizedlist>
	    <listitem>
	      <para>If you are convinced that the problem will only
		occur under the processor architecture you are using,
		select one of the architecture-specific categories:
		commonly <literal>i386</literal> for Intel-compatible
		machines in 32-bit mode; <literal>amd64</literal> for
		AMD machines running in 64-bit mode (this also
		includes Intel-compatible machines running in EMT64
		mode); and less commonly <literal>arm</literal>,
		<literal>ia64</literal>, <literal>powerpc</literal>,
		and <literal>sparc64</literal>.</para>

	      <note>
		<para>These categories are quite often misused for
		  <quote>I do not know</quote> problems.  Rather than
		  guessing, please just use
		  <literal>misc</literal>.</para>
	      </note>

	      <example>
		<title>Correct Use of Arch-Specific Category</title>

		<para>You have a common PC-based machine, and think
		  you have encountered a problem specific to a
		  particular chipset or a particular motherboard:
		  <literal>i386</literal> is the right
		  category.</para>
	      </example>

	      <example>
		<title>Incorrect Use of Arch-Specific Category</title>

		<para>You are having a problem with an add-in
		  peripheral card on a commonly seen bus, or a problem
		  with a particular type of hard disk drive: in this
		  case, it probably applies to more than one
		  architecture, and <literal>kern</literal> is the
		  right category.</para>
	      </example>
	    </listitem>

	    <listitem>
	      <para>If you really do not know where the problem lies
		(or the explanation does not seem to fit into the ones
		above), use the <literal>misc</literal> category.
		Before you do so, you may wish to ask for help on the
		&a.questions; first.  You may be advised that one of
		the existing categories really is a better
		choice.</para>
	    </listitem>
	  </itemizedlist>

	  <para>Here is the current list of categories (taken from
	    <uri
	      xlink:href="http://svnweb.freebsd.org/base/head/gnu/usr.bin/send-pr/categories">http://svnweb.freebsd.org/base/head/gnu/usr.bin/send-pr/categories</uri>):</para>

	  <itemizedlist>
	    <listitem>
	      <para><literal>advocacy:</literal> problems relating to
		&os;'s public image.  Obsolete.</para>
	    </listitem>

	    <listitem>
	      <para><literal>amd64:</literal> problems specific to the
		AMD64 platform.</para>
	    </listitem>

	    <listitem>
	      <para><literal>arm:</literal> problems specific to the
		ARM platform.</para>
	    </listitem>

	    <listitem>
	      <para><literal>bin:</literal> problems with userland
		programs in the base system.</para>
	    </listitem>

	    <listitem>
	      <para><literal>conf:</literal> problems with
		configuration files, default values, and so
		forth.</para>
	    </listitem>

	    <listitem>
	      <para><literal>docs:</literal> problems with manual
		pages or on-line documentation.</para>
	    </listitem>

	    <listitem>
	      <para><literal>gnu:</literal> problems with imported GNU
		software such as &man.gcc.1; or &man.grep.1;.</para>
	    </listitem>

	    <listitem>
	      <para><literal>i386:</literal> problems specific to the
		&i386; platform.</para>
	    </listitem>

	    <listitem>
	      <para><literal>ia64:</literal> problems specific to the
		ia64 platform.</para>
	    </listitem>

	    <listitem>
	      <para><literal>java:</literal> problems related to the
		&java; Virtual Machine.</para>
	    </listitem>

	    <listitem>
	      <para><literal>kern:</literal> problems with
		the kernel, (non-platform-specific) device drivers,
		or the base libraries.</para>
	    </listitem>

	    <listitem>
	      <para><literal>misc:</literal> anything that does not
		fit in any of the other categories.  (Note that there
		is almost nothing that truly belongs in this category,
		except for problems with the release and build
		infrastructure.  Temporary build failures on
		<literal>HEAD</literal> do not belong here.  Also note
		that it is easy for things to get lost in this
		category).</para>
	    </listitem>

	    <listitem>
	      <para><literal>ports:</literal> problems relating to the
		Ports Collection.</para>
	    </listitem>

	    <listitem>
	      <para><literal>powerpc:</literal> problems specific to
		the &powerpc; platform.</para>
	    </listitem>

	    <listitem>
	      <para><literal>sparc64:</literal> problems specific to
		the &sparc64; platform.</para>
	    </listitem>

	    <listitem>
	      <para><literal>standards:</literal> Standards
		conformance issues.</para>
	    </listitem>

	    <listitem>
	      <para><literal>threads:</literal> problems related to
		the &os; threads implementation (especially on
		&os.current;).</para>
	    </listitem>

	    <listitem>
	      <para><literal>usb:</literal> problems related to the
		&os; USB implementation.</para>
	    </listitem>

	    <listitem>
	      <para><literal>www:</literal> Changes or enhancements to
		the &os; website.</para>
	    </listitem>
	  </itemizedlist>
	</listitem>

	<listitem>
	  <para><emphasis>Class:</emphasis> Choose one of the
	    following:</para>

	  <itemizedlist>
	    <listitem>
	      <para><literal>sw-bug:</literal> software bugs.</para>
	    </listitem>

	    <listitem>
	      <para><literal>doc-bug:</literal> errors in
		documentation.</para>
	    </listitem>

	    <listitem>
	      <para><literal>change-request:</literal> requests for
		additional features or changes in existing
		features.</para>
	    </listitem>

	    <listitem>
	      <para><literal>update:</literal> updates to ports or
		other contributed software.</para>
	    </listitem>

	    <listitem>
	      <para><literal>maintainer-update:</literal> updates to
		ports for which you are the maintainer.</para>
	    </listitem>
	  </itemizedlist>
	</listitem>

	<listitem>
	  <para><emphasis>Release:</emphasis> The version of &os;
	    that you are running.  This is filled out automatically if
	    you are using &man.send-pr.1; and need only be changed if
	    you are sending a problem report from a different system
	    than the one that exhibits the problem.</para>
	</listitem>
      </itemizedlist>

      <para>Finally, there is a series of multi-line fields:</para>

      <itemizedlist>
	<listitem>
	  <para><emphasis>Environment:</emphasis>  This should
	    describe, as accurately as possible, the environment in
	    which the problem has been observed.  This includes the
	    operating system version, the version of the specific
	    program or file that contains the problem, and any other
	    relevant items such as system configuration, other
	    installed software that influences the problem,
	    etc.&mdash;quite simply everything a developer needs to
	    know to reconstruct the environment in which the problem
	    occurs.</para>
	</listitem>

	<listitem>
	  <para><emphasis>Description:</emphasis>  A complete and
	    accurate description of the problem you are experiencing.
	    Try to avoid speculating about the causes of the problem
	    unless you are certain that you are on the right track, as
	    it may mislead a developer into making incorrect
	    assumptions about the problem.</para>
	</listitem>

	<listitem>
	  <para><emphasis>How-To-Repeat:</emphasis>  A summary of the
	    actions you need to take to reproduce the problem.</para>
	</listitem>

	<listitem>
	  <para><emphasis>Fix:</emphasis>  Preferably a patch, or at
	    least a workaround (which not only helps other people with
	    the same problem work around it, but may also help a
	    developer understand the cause for the problem), but if
	    you do not have any firm ideas for either, it is better to
	    leave this field blank than to speculate.</para>
	</listitem>
      </itemizedlist>
    </section>

    <section xml:id="pr-writing-sending">
      <title>Sending the Problem Report</title>

      <para>If you are using &man.send-pr.1;:</para>

      <para>Once you are done filling out the template, have saved it,
	and exit your editor, &man.send-pr.1; will prompt you with
	<prompt>s)end, e)dit or a)bort?</prompt>.  You can then hit
	<userinput>s</userinput> to go ahead and submit the problem
	report, <userinput>e</userinput> to restart the editor and
	make further modifications, or <userinput>a</userinput> to
	abort.  If you choose the latter, your problem report will
	remain on disk (&man.send-pr.1; will tell you the filename
	before it terminates), so you can edit it at your leisure, or
	maybe transfer it to a system with better net connectivity,
	before sending it with the <option>-f</option> to
	&man.send-pr.1;:</para>

      <screen>&prompt.user; <userinput>send-pr -f ~/my-problem-report</userinput></screen>

      <para>This will read the specified file, validate the contents,
	strip comments and send it off.</para>

      <para>If you are using the <link
	  xlink:href="https://bugs.freebsd.org/bugzilla/enter_bug.cgi">web form</link>:</para>

      <para>Before you hit <literal>submit</literal>, you will need to
	fill in a field containing text that is represented in image
	form on the page.  This unfortunate measure has had to be
	adopted due to misuse by automated systems and a few misguided
	individuals.  It is a necessary evil that no one likes; please
	do not ask us to remove it.</para>

      <para>Note that you are <literal>strongly advised</literal> to
	save your work somewhere before hitting
	<literal>submit</literal>.  A common problem for users is to
	have their web browser displaying a stale image from its
	cache.  If this happens to you, your submission will be
	rejected and you may lose your work.</para>

      <para>If you are unable to view images for any reason, and are
	also unable to use &man.send-pr.1;, please accept our
	apologies for the inconvenience and email your problem report
	to the bugbuster team at
	<email>freebsd-bugbusters@FreeBSD.org</email>.</para>
    </section>
  </section>

  <section xml:id="pr-followup">
    <title>Follow-up</title>

    <para>Once the problem report has been filed, you will receive a
      confirmation by email which will include the tracking number
      that was assigned to your problem report and a URL you can use
      to check its status.  With a little luck, someone will take an
      interest in your problem and try to address it, or, as the case
      may be, explain why it is not a problem.  You will be
      automatically notified of any change of status, and you will
      receive copies of any comments or patches someone may attach to
      your problem report's audit trail.</para>

    <para>If someone requests additional information from you, or you
      remember or discover something you did not mention in the
      initial report, please submit a follow up.  The number one
      reason for a bug not getting fixed is lack of communication with
      the originator.</para>

    <itemizedlist>
      <listitem>
	<para>The easiest way is to use the comment option on the
	  individual PR's web page, which you can reach from the <link
	    xlink:href="https://bugs.freebsd.org/bugzilla/query.cgi">PR
	    search page</link>.</para>
      </listitem>
    </itemizedlist>

    <para>If the problem report remains open after the problem has
      gone away, just add a comment
      saying that the problem report can be closed, and, if
      possible, explaining how or when the problem was fixed.</para>

    <para>Sometimes there is a delay of a week or two where the
      problem report remains untouched, not assigned or commented on
      by anyone.  This can happen when there is an increased problem
      report backlog or during a holiday season.  When a problem
      report has not received attention after several weeks, it is
      worth finding a committer particularly interested in working on
      it.</para>

    <para>There are a few ways to do so, ideally in the following
      order, with a few days between attempting each communication
      channel:</para>

    <itemizedlist>
      <listitem>
	<para>Find the relevant &os; mailing list for the problem
	  report from the <link
	    xlink:href="&url.books.handbook;/eresources.html#ERESOURCES-MAIL">list
	    in the Handbook</link> and send a message to that list
	  asking about assistance or comments on the problem
	  report.</para>
      </listitem>

      <listitem>
	<para>Join the relevant <acronym>IRC</acronym> channels.
	  A partial listing is here: <link
	    xlink:href="https://wiki.freebsd.org/IrcChannels"></link>.
	  Inform the people in that channel about the problem report
	  and ask for assistance.  Be patient and stay in the channel
	  after posting, so that the people from different time zones
	  around the world have a chance to catch up.</para>
      </listitem>

      <listitem>
	<para>Find committers interested in the problem that was
	  reported.  If the problem was in a particular tool, binary,
	  port, document, or source file, check the <link
	    xlink:href="http://svnweb.FreeBSD.org">SVN
	    Repository</link>.  Locate the last few committers who
	  made substantive changes to the file, and try to reach them
	  via <acronym>IRC</acronym> or email.  A list of committers
	  and their emails can be found in the <link
	    xlink:href="&url.articles.contributors.en;">Contributors
	    to &os;</link> article.</para>
      </listitem>
    </itemizedlist>

    <para>Remember that these people are volunteers, just like
      maintainers and users, so they might not be immediately
      available to assist with the problem report.  Patience and
      consistency in the follow-ups is highly advised and appreciated.
      With enough care and effort dedicated to that follow-up process,
      finding a committer to take care of the problem report is just a
      matter of time.</para>
  </section>

  <section xml:id="pr-problems">
    <title>If There Are Problems</title>

    <para>If you found an issue with the bug system, file a bug!
      There is a category for exactly this purpose.  If you are unable
      to do so, contact the bug wranglers at
      <email>bugmeister@FreeBSD.org</email>.</para>
  </section>

  <section xml:id="pr-further">
    <title>Further Reading</title>

    <para>This is a list of resources relevant to the proper writing
      and processing of problem reports.  It is by no means
      complete.</para>

    <itemizedlist>
      <listitem>
	<para><link
	    xlink:href="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html">How
	    to Report Bugs Effectively</link>&mdash;an excellent essay
	  by Simon G. Tatham on composing useful (non-&os;-specific)
	  problem reports.</para>
      </listitem>

      <listitem>
	<para><link
	    xlink:href="&url.articles.pr-guidelines;/article.html">Problem
	  Report Handling Guidelines</link>&mdash;valuable insight
	  into how problem reports are handled by the &os;
	  developers.</para>
      </listitem>
    </itemizedlist>
  </section>

  <index/>
</article>