<!DOCTYPE HTML PUBLIC "-//FreeBSD//DTD HTML 4.01 Transitional-Based Extension//EN" [
<!ENTITY base CDATA "../..">
<!ENTITY date "$FreeBSD$">
<!ENTITY title "FreeBSD GNOME Project: Reporting a Bug">
<!ENTITY email "freebsd-gnome">
<!ENTITY % navinclude.gnome "INCLUDE">
]>

<html>
  &header;

		  <h2>1. When should I make a bug report?</h2>
		  <ul>
		    <li><b><i>After</i></b> running any build failure
		      output through <a
		      href="/gnome/gnomelogalyzer.sh">gnomelogalyzer.sh</a>.
		    <li><b><i>After</i></b> running <tt>cvsup</tt> to obtain the most
		      recent ports tree.
		    <li><b><i>After</i></b> running <tt>portupgrade&nbsp;-a</tt> or
		      <tt>portmaster&nbsp;-a</tt> to ensure that all applications are
		      up-to-date. Do not forget to read in <tt>/usr/ports/UPDATING</tt>
		      first before you upgrade those installed ports.
		    <li><b><i>After</i></b> searching through the FreeBSD GNOME
              <a href="&base;/gnome/index.html#search">Mailing
			  list archives</a> to see if the problem has already been
			  reported.
		    <li><b><i>After</i></b> deciding whether the problem is FreeBSD-specific,
		      or is a bug in an application that would affect all users,
		      on all operating systems. If you cannot determine if the
		      problem is FreeBSD-specific or not, then send your
		      problem to the <a
		      href="mailto:&email;@FreeBSD.org">freebsd-gnome mailing
		      list</a>, and we can help decide where the problem lies.
		  </ul>

          <h2>2. What to report?</h2>

		  <p>Always report as much information as you can.  Too much
		information is always preferable to too little information.
		Superfluous information can be filtered out; developers like
		to play guessing games with code, not with bug reports.</p>

          <p>A good bug report should at least include the following
		information:</p>

          <ul>
	    <li><p>Exact version of the operating system (usually output of
	      <tt>uname -a</tt>).</p></li>
	    <li><p>List of all packages installed on your system (output of
		  <tt>pkg_info</tt>).</p></li>
	    <li><p>Your environment (output of <tt>/usr/bin/env</tt>).
	    <li><p>If you are building from ports, note approximately how
		  long it has been since you last updated your ports tree.  If
		  it has been more than a day, or if you have not run
		  <tt>portupgrade&nbsp;-a</tt> or <tt>portmaster&nbsp;-a</tt>,
		  do not bother sending a bug report until you have run
		  <tt>cvsup</tt> and <tt>portupgrade/portmaster</tt>.</p></li>
	    <li><p>Information specific for each type of breakage:</p>
		  <ul>
		    <li>If a port will not build, provide a full log of the
		      unsuccessful build by either uploading it to any website,
		      copy-and-paste to <a
		      href="http://freebsd-gnome.pastebin.com">http://freebsd-gnome.pastebin.com</a>,
		      or send-pr(1) with attachment. Try to avoid sending any
		      attachments to the mailing list, because attachments sent
		      to FreeBSD mailing lists are usually discarded by the
		      mailing list software.
		    <li>If a program produces a core dump, provide a
		      back trace.  Back traces are only useful if the
		      application (and possibly its dependencies) are
		      compiled with debugging symbols.  See these
		      <a
		      href="http://live.gnome.org/GettingTraces">instructions</a>
		      for more information on obtaining useful back
			traces.  In general, though, you can build and
			install your port with the following command
			to produce binaries that will have useful
			debugging symbols: <tt>make WITH_DEBUG=yes install</tt>
		    <li>If an application produces unexpected behavior,
		      provide a clear and detailed description, including a
		      description of the behavior that you were expecting.
		   </ul>
		 </li>
         </ul>

          <p>If you have a solution or a workaround for the problem, then include
            it into your report as well, even if you are not quite sure that
	    it is a proper fix.  Even if the fix is not quite right, it could still
		point others in the right direction.
	  </p>

          <h2>3. Where to report?</h2>

          <p>Once you are sure it is a new problem, there are several ways
	    to report a bug in GNOME running on FreeBSD: you could
	    send a report to the
	    <a href="mailto:&email;@FreeBSD.org">freebsd-gnome mailing
	    list</a>, file a problem report in the
	    <a href="http://www.FreeBSD.org/support.html#gnats">FreeBSD bug
	    reporting system</a>, send your report to the application's
	    developers via the GNOME
	    <a href="http://bugzilla.gnome.org/">bug tracking system</a>, or
	    any combination of those.<p>

          <ul>
            <li><p>If the problem is FreeBSD-specific (usually, this means
			  a problem with building or upgrading), then report to the
			  <a href="mailto:&email;@FreeBSD.org">freebsd-gnome mailing
			  list</a>, or file a bug report through the
	          <a href="http://www.FreeBSD.org/support.html#gnats">FreeBSD bug
			  reporting system</a>.</p></li>
			<li><p>If the problem has to do with an application's
			  behavior, report the problem directly to the application's
			  developers through the GNOME project's
	          <a href="http://bugzilla.gnome.org/">bug tracking system</a></p></li>
			<li><p>If the problem is quite serious, not necessarily
			  FreeBSD-specific, <i>and</i> you have a fix available, report
			  it to both the FreeBSD GNOME team and the application's
			  developers.  This way, the application's developers can apply
			  the patch upstream, and the FreeBSD GNOME team can apply the
			  patch immediately to the ports tree without needing to wait
			  for the next release.</p></li>
          </ul>

    &footer;
  </body>
</html>
