Annotation of www/report.html, Revision 1.18
1.18 ! jufi 1: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
1.4 deraadt 2: <html>
3: <head>
4: <title>OpenBSD problem reports</title>
1.18 ! jufi 5: <link rev=made href="mailto:www@openbsd.org">
1.4 deraadt 6: <meta name="resource-type" content="document">
1.18 ! jufi 7: <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
1.4 deraadt 8: <meta name="description" content="OpenBSD problem report page">
9: <meta name="keywords" content="openbsd,problemreports">
10: <meta name="distribution" content="global">
1.16 horacio 11: <meta name="copyright" content="This document copyright 1998-2002 by OpenBSD.">
1.4 deraadt 12: </head>
13:
14: <body bgcolor="#ffffff" text="#000000" link="#23238e">
1.17 jsyn 15: <a href="index.html"><img alt="[OpenBSD]" height="30" width="141" src="images/smalltitle.gif" border="0"></a>
1.5 deraadt 16: <p>
1.18 ! jufi 17: <h2><font color="#e00000">How to report a Problem</font></h2>
! 18: <hr>
1.5 deraadt 19:
1.18 ! jufi 20: <h3><font color="#0000e0">Released versions problem reports</font></h3>
1.4 deraadt 21:
1.5 deraadt 22: Before reporting bugs/problems with released versions,
1.1 deraadt 23: go through this checklist:
1.4 deraadt 24: <ol>
25: <li>First check for <a href="http://www.openbsd.org/errata.html">patches
26: and notes regarding the release.</a>
27: <li>Next find out if there is a <a href="http://www.openbsd.org/orders.html">
28: newer release available.</a>
29: <li>The last thing to check is for <a href="http://www.openbsd.org/plus.html">
30: changes made between OpenBSD versions.</a>
31: </ol>
32: <p>
1.9 chris 33: If nothing looks like it addresses your problem, then please become acquainted
34: with
1.18 ! jufi 35: <a href="http://www.openbsd.org/cgi-bin/man.cgi?query=sendbug&sektion=1&format=html">
1.9 chris 36: sendbug(1)</a>
1.4 deraadt 37: before submitting a bug report.
38: <p>
39: Read further down for the <a href="#bugtypes">types of bug reports</a> desired.
40:
1.18 ! jufi 41: <h3><font color="#0000e0">Current version problem reports</font></h3>
1.9 chris 42:
43: If your problem is with the <i>current</i> source tree rather then a <i>release</i> or
44: <i>stable</i> tree,
1.5 deraadt 45:
1.4 deraadt 46: <ol>
47: <li>Test the problem at least twice, with source updated a few days apart.
48: <li>Do not report source tree compilation problems, unless they persist.
1.1 deraadt 49: They are almost always your mistake or they are being worked on
50: as you encounter them. People working on the project are
1.4 deraadt 51: doing <u>make build</u> at least once per day, and usually several times
1.1 deraadt 52: per day with different architectures.
1.4 deraadt 53: <li>Remember that the <a href="http://www.openbsd.org/anoncvs.html">anoncvs</a>
1.1 deraadt 54: servers are updated significantly behind the actual working source tree.
1.4 deraadt 55: <li>Check for <a href="http://www.openbsd.org/plus.html">changes
56: made between OpenBSD versions</a> to see if the problem has been
1.1 deraadt 57: addressed.
1.4 deraadt 58: <li>Much care is made in creating snapshots. Sometimes mistakes are made,
1.1 deraadt 59: and our apologies are extended. Reading/writing the e-mail lists
60: is more appropriate than sending in a bug report.
1.4 deraadt 61: </ol>
62: <br>
1.5 deraadt 63:
1.18 ! jufi 64: <h3><font color="#0000e0">How to create a problem report</font></h3>
1.8 chris 65:
66: <b>Always provide as much information as possible</b>.
1.9 chris 67: Try to pin-point the exact problem. Never give vague instructions,
68: or detail vague problems like "it crashes" or "I get strange interrupt
69: issues on this one box that I built." Talk to others on IRC or some
70: other forum to confirm that it is new, repeatable, etc. and make sure
71: it is not a local problem.
72: <P>Please don't start fixing problems that
73: require significant work until you are sure you understand them, especially
74: during our release periods when we must not change major sections of code.
75: If you are going to write significant amounts of code, check various
76: forums to make sure that someone else is not working on the problem
77: (saving duplication of effort).
78: <P>
1.8 chris 79: The following items should be contained in every bug report:
80: <ol>
81: <li>The exact sequence of steps from startup necessary to reproduce
82: the problem. This should be self-contained; it is not enough to send in
83: a bare command without the arguments and other data you supplied to it.
84: If a bug requires a particular sequence of events, please list those.
85: You are encouraged to minimize the size of your example, but this is
1.12 jsyn 86: not absolutely necessary. If the bug is reproducible, we'll find it
1.8 chris 87: either way.
88: <p>
89: <li>The output you got. Please do not say that it "didn't work" or
90: "failed". If there is an error message, show it, even if you don't
91: understand it. If OpenBSD panics with a particular error, say which.
92: If nothing at all happens, say so. Even if the result
93: of your test case is a program crash or otherwise obvious it might not
94: happen in our testing. The easiest thing is to copy the output from
95: the terminal, if possible.
96: <p>
97:
98: Note: In case of fatal errors, the error message provided
99: might not contain all the information available.
100: In that case, also look at the output in the system log files,
101: such as those stored in /var/log. Also, if you are dealing with
102: an application that has its own log files, such as httpd, check
103: for errors where it keeps its logs (in the case of httpd, this
104: is /var/www/logs).
105:
106: <p>
107: <li>The OpenBSD kernel output. You can get this with the dmesg command,
108: but it is possible that your dmesg output does not contain all the
109: information that is captured in /var/run/dmesg.boot. If this is the
110: case, include information from both. <b>Please include this
111: in all bug reports.</b>
1.14 miod 112: <p>
113: <li> If you run third-party software which has to do with your bug, say so,
114: including any subversion that software may have. If you are talking about
115: a CVS or FTP snapshot, mention that, including its date and time.
116: <p>
117: <li>A traceback from your kernel panic. If your kernel panic'ed, and you
1.18 ! jufi 118: are at a <tt><a href="http://www.openbsd.org/cgi-bin/man.cgi?query=ddb&sektion=4&format=html">ddb</a>></tt>
1.15 miod 119: prompt, then please provide the panic message, as well as the output of
120: the <tt>traceback</tt> and <tt>ps</tt> commands in your bug report as
121: advised.<br>
122: If, for some reason, the panic message is not visible, you can get it
123: again with the <tt>x/s *panicstr</tt> command.<br>
124: <b>This is essential whenever possible. Panic reports without panic message,
125: traceback and ps output are useless.</b><br>
1.14 miod 126: The output of <tt>show registers</tt> might be of interest as well.
127: You might then want to reboot with <tt>boot dump</tt> so that a kernel
1.18 ! jufi 128: image could be saved by <a href="http://www.openbsd.org/cgi-bin/man.cgi?query=savecore&sektion=8&format=html">savecore(8)</a>
1.14 miod 129: for further post-mortem debugging.
1.8 chris 130:
131: </ol>
132: <p>
133: Do not be afraid if your bug report becomes rather lengthy. That is a fact
134: of life. It's better to report everything the first time than us having to
135: squeeze the facts out of you. On the other hand, if your input files are
136: huge, it is fair to ask first whether somebody is interested in looking into
137: it.
138: <P>
139: Finally, when writing a bug report, please choose non-confusing terminology.
140:
1.10 jufi 141: <a name="bugtypes"></a>
1.18 ! jufi 142: <h3><font color="#0000e0">Sending in bug reports</font></h3>
1.9 chris 143: <P>
1.18 ! jufi 144: 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.
1.9 chris 145: You can follow the tracking system at <A HREF="http://cvs.openbsd.org/cgi-bin/wwwgnats.pl">this web page</a>.
146: Sendbug requires that your system can properly send Internet email. If you
147: cannot use sendbug on a functional OpenBSD machine, please send your bug report
148: to <A HREF="mailto:bugs@openbsd.org">bugs@openbsd.org</a>.
149: <P>
150: Perhaps what you are sending in is a feature request, not necessarily a bug.
1.1 deraadt 151: New features are accepted, especially with code that implements
152: your suggested new feature.
153: If someone else writes code for your new feature, the chances are that
154: it will be misunderstood and created so that you will not recognize it.
155:
1.4 deraadt 156: <p>
1.5 deraadt 157: For debugging some problems, we must have the hardware that has the
158: problem. Please remember that projects resources are limited.
159: <a href="http://www.openbsd.org/want.html">You could donate some hardware.</a>
1.1 deraadt 160:
1.4 deraadt 161: <p>
1.1 deraadt 162: Types of bug reports in order of desirability:
1.4 deraadt 163: <ol>
164: <li>Repeatable problems with source fixes are the best.
165: <li>Repeatable problems that are not specific to your hardware/software
1.1 deraadt 166: layout.
1.4 deraadt 167: <li>Repeatable problems specific to your software layout.
168: <li>Repeatable problems specific to your hardware layout.
169: <li>Non-repeatable problems -- or problems you do not wish to repeat.
170: </ol>
1.1 deraadt 171:
172: <hr>
1.18 ! jufi 173: <img align=right alt="OpenBSDPower" height=46 width=201 src="images/openbsdpower.gif">
! 174: <a href="index.html"><img height=24 width=24 src="back.gif" border=0 alt=OpenBSD></a>
! 175: <a href="mailto:www@openbsd.org">www@openbsd.org</a>
1.7 wvdputte 176:
1.18 ! jufi 177: <br><small>$OpenBSD: report.html,v 1.17 2002/06/18 01:44:06 jsyn Exp $</small>
1.1 deraadt 178:
1.4 deraadt 179: </body>
180: </html>