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