File: [local] / www / report.html (download) (as text)
Revision 1.18, Thu Jul 4 11:24:50 2002 UTC (21 years, 11 months ago) by jufi
Branch: MAIN
Changes since 1.17: +17 -18 lines
cleanup
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>OpenBSD problem reports</title>
<link rev=made href="mailto:www@openbsd.org">
<meta name="resource-type" content="document">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="description" content="OpenBSD problem report page">
<meta name="keywords" content="openbsd,problemreports">
<meta name="distribution" content="global">
<meta name="copyright" content="This document copyright 1998-2002 by OpenBSD.">
</head>
<body bgcolor="#ffffff" text="#000000" link="#23238e">
<a href="index.html"><img alt="[OpenBSD]" height="30" width="141" src="images/smalltitle.gif" border="0"></a>
<p>
<h2><font color="#e00000">How to report a Problem</font></h2>
<hr>
<h3><font color="#0000e0">Released versions problem reports</font></h3>
Before reporting bugs/problems with released versions,
go through this checklist:
<ol>
<li>First check for <a href="http://www.openbsd.org/errata.html">patches
and notes regarding the release.</a>
<li>Next find out if there is a <a href="http://www.openbsd.org/orders.html">
newer release available.</a>
<li>The last thing to check is for <a href="http://www.openbsd.org/plus.html">
changes made between OpenBSD versions.</a>
</ol>
<p>
If nothing looks like it addresses your problem, then please become acquainted
with
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=sendbug&sektion=1&format=html">
sendbug(1)</a>
before submitting a bug report.
<p>
Read further down for the <a href="#bugtypes">types of bug reports</a> desired.
<h3><font color="#0000e0">Current version problem reports</font></h3>
If your problem is with the <i>current</i> source tree rather then a <i>release</i> or
<i>stable</i> tree,
<ol>
<li>Test the problem at least twice, with source updated a few days apart.
<li>Do not report source tree compilation problems, unless they persist.
They are almost always your mistake or they are being worked on
as you encounter them. People working on the project are
doing <u>make build</u> at least once per day, and usually several times
per day with different architectures.
<li>Remember that the <a href="http://www.openbsd.org/anoncvs.html">anoncvs</a>
servers are updated significantly behind the actual working source tree.
<li>Check for <a href="http://www.openbsd.org/plus.html">changes
made between OpenBSD versions</a> to see if the problem has been
addressed.
<li>Much care is made in creating snapshots. Sometimes mistakes are made,
and our apologies are extended. Reading/writing the e-mail lists
is more appropriate than sending in a bug report.
</ol>
<br>
<h3><font color="#0000e0">How to create a problem report</font></h3>
<b>Always provide as much information as possible</b>.
Try to pin-point the exact problem. Never give vague instructions,
or detail vague problems like "it crashes" or "I get strange interrupt
issues on this one box that I built." Talk to others on IRC or some
other forum to confirm that it is new, repeatable, etc. and make sure
it is not a local problem.
<P>Please don't start fixing problems that
require significant work until you are sure you understand them, especially
during our release periods when we must not change major sections of code.
If you are going to write significant amounts of code, check various
forums to make sure that someone else is not working on the problem
(saving duplication of effort).
<P>
The following items should be contained in every bug report:
<ol>
<li>The exact sequence of steps from startup necessary to reproduce
the problem. This should be self-contained; it is not enough to send in
a bare command without the arguments and other data you supplied to it.
If a bug requires a particular sequence of events, please list those.
You are encouraged to minimize the size of your example, but this is
not absolutely necessary. If the bug is reproducible, we'll find it
either way.
<p>
<li>The output you got. Please do not say that it "didn't work" or
"failed". If there is an error message, show it, even if you don't
understand it. If OpenBSD panics with a particular error, say which.
If nothing at all happens, say so. Even if the result
of your test case is a program crash or otherwise obvious it might not
happen in our testing. The easiest thing is to copy the output from
the terminal, if possible.
<p>
Note: In case of fatal errors, the error message provided
might not contain all the information available.
In that case, also look at the output in the system log files,
such as those stored in /var/log. Also, if you are dealing with
an application that has its own log files, such as httpd, check
for errors where it keeps its logs (in the case of httpd, this
is /var/www/logs).
<p>
<li>The OpenBSD kernel output. You can get this with the dmesg command,
but it is possible that your dmesg output does not contain all the
information that is captured in /var/run/dmesg.boot. If this is the
case, include information from both. <b>Please include this
in all bug reports.</b>
<p>
<li> If you run third-party software which has to do with your bug, say so,
including any subversion that software may have. If you are talking about
a CVS or FTP snapshot, mention that, including its date and time.
<p>
<li>A traceback from your kernel panic. If your kernel panic'ed, and you
are at a <tt><a href="http://www.openbsd.org/cgi-bin/man.cgi?query=ddb&sektion=4&format=html">ddb</a>></tt>
prompt, then please provide the panic message, as well as the output of
the <tt>traceback</tt> and <tt>ps</tt> commands in your bug report as
advised.<br>
If, for some reason, the panic message is not visible, you can get it
again with the <tt>x/s *panicstr</tt> command.<br>
<b>This is essential whenever possible. Panic reports without panic message,
traceback and ps output are useless.</b><br>
The output of <tt>show registers</tt> might be of interest as well.
You might then want to reboot with <tt>boot dump</tt> so that a kernel
image could be saved by <a href="http://www.openbsd.org/cgi-bin/man.cgi?query=savecore&sektion=8&format=html">savecore(8)</a>
for further post-mortem debugging.
</ol>
<p>
Do not be afraid if your bug report becomes rather lengthy. That is a fact
of life. It's better to report everything the first time than us having to
squeeze the facts out of you. On the other hand, if your input files are
huge, it is fair to ask first whether somebody is interested in looking into
it.
<P>
Finally, when writing a bug report, please choose non-confusing terminology.
<a name="bugtypes"></a>
<h3><font color="#0000e0">Sending in bug reports</font></h3>
<P>
If possible, use the <A HREF="http://www.openbsd.org/cgi-bin/man.cgi?query=sendbug&sektion=1&format=html">sendbug(1)</a> command to get the bug into our tracking system.
You can follow the tracking system at <A HREF="http://cvs.openbsd.org/cgi-bin/wwwgnats.pl">this web page</a>.
Sendbug requires that your system can properly send Internet email. If you
cannot use sendbug on a functional OpenBSD machine, please send your bug report
to <A HREF="mailto:bugs@openbsd.org">bugs@openbsd.org</a>.
<P>
Perhaps what you are sending in is a feature request, not necessarily a bug.
New features are accepted, especially with code that implements
your suggested new feature.
If someone else writes code for your new feature, the chances are that
it will be misunderstood and created so that you will not recognize it.
<p>
For debugging some problems, we must have the hardware that has the
problem. Please remember that projects resources are limited.
<a href="http://www.openbsd.org/want.html">You could donate some hardware.</a>
<p>
Types of bug reports in order of desirability:
<ol>
<li>Repeatable problems with source fixes are the best.
<li>Repeatable problems that are not specific to your hardware/software
layout.
<li>Repeatable problems specific to your software layout.
<li>Repeatable problems specific to your hardware layout.
<li>Non-repeatable problems -- or problems you do not wish to repeat.
</ol>
<hr>
<img align=right alt="OpenBSDPower" height=46 width=201 src="images/openbsdpower.gif">
<a href="index.html"><img height=24 width=24 src="back.gif" border=0 alt=OpenBSD></a>
<a href="mailto:www@openbsd.org">www@openbsd.org</a>
<br><small>$OpenBSD: report.html,v 1.18 2002/07/04 11:24:50 jufi Exp $</small>
</body>
</html>
![[BACK]](/icons/back.gif){kind=icon}
Return to report.html CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / www