cvs: php-bugs-web / how-to-report.php

jimw Sun Sep 23 21:07:55 2001 EDT Modified files: /php-bugs-web how-to-report.php Log: rewrite. include links to other nice how-to-report-bugs pages.

Index: php-bugs-web/how-to-report.php diff -u php-bugs-web/how-to-report.php:1.1 php-bugs-web/how-to-report.php:1.2 --- php-bugs-web/how-to-report.php:1.1 Sun Sep 23 19:27:04 2001 +++ php-bugs-web/how-to-report.php Sun Sep 23 21:07:55 2001 @@ -5,46 +5,127 @@ <h1>How to Report a Bug</h1> +<p>There is a large number of PHP users. There is a much small number of people +who actually develop the PHP language and extensions. There is an even smaller +number of people who actively fix bugs reported by users.</p> + +<p>What does this mean for you, an aspiring bug reporter? In order to catch the +eye of one of these few stalwart <b>volunteers</b>, you'll need to take to +heart a few tips on how to report a bug so that they can and will help you.</p> + +<p>Take special note of that word in bold above. The people who are going to +help you with a bug you report are <b>volunteers</b>. Not only are you not +paying them to help you, but nobody else is either. So, to paraphrase the +immortal words of <a href="http://www.imdb.com/Title?0096928">Bill and Ted</a>, +<b>"be excellent to them"</b>.</p> + +<p>Beyond that golden rule, what follows are some additional tips on ways to +make your bug report better so that someone will be able to help you.</p> + +<h2>The basics: what you did, what you wanted to happen, and what actually +happened.</h2> + +<p>Those are the three basic elements of a bug report. You need to tell us +exactly what you did (for example, "My script calls +make_happy_meal('hamburger','onion rings')") , what you expected to have happen +(to continue the example, "I expected PHP to serve me a happy meal with a +hamburger and onion rings"), and what actually happened ("It gave me a happy +meal with french fries.").</p> + +<p>Yes, the example is silly. But if your bug report simply said "The +make_happy_meal function doesn't work," we wouldn't be able to say "That's +because you can't have onion rings in a happy meal, you can only have french +fries or curly fries." By telling us what you asked for, what you expected to +get, and what you actually got, we don't have to guess.</p> + +<h2>Always search the bug database first.</h2> + +<p>Advice so good, we'll repeat it twice. Always <a +href="search.php">search</a> the bug database first. As we said above, there's +a lot of users of PHP. The odds are good that if you've found a problem, +someone else has found it, too. If you spend a few minutes of your time making +sure that you're not filing a duplicate bug, that's a few more minutes someone +can spend helping to fix that bug rather than sorting out duplicate bug +reports.</p> + +<h2>If you don't understand an error message, ask for help.</h2> + +<p>Don't report an error message you don't understand as a bug. There are <a +href="http://www.php.net/support.php">a lot of places you can ask for help</a> +in understanding what is going on before you can claim that an error message +you do not understand is a bug.</p> + +<p>(Now, once you've understood the error message, and have a good suggestion +for a way to make the error message more clear, you might consider reporting it +as a feature request.)</p> + +<h2>Be brief, but don't leave any important details out.</h2> + +<p>This is a fine line to walk. But there are some general guidelines:</p> <ul> -<li>Please don't report bugs in versions older than two revisions - before the latest one available. E.g., if the latest revision - is 4.0.6, please don't report problems in versions earlier than - 4.0.4. Instead, upgrade first to the latest version, and see - if the problem isn't solved. Only if it isn't - submit a bug - report here.</li> -<li>Don't report missing functions in the documentation as a - 'documentation problem', or as anything else. We have an - uptodate list of which functions are missing from the - documentation, and the only reason they're missing from - there is that nobody had the time to document them just yet. - Consult the PHP mailing list - (<a href="mailto:php-general@lists.php.net">php-general@lists.php.net</a>) - instead, and if you gather enough information - feel free to - submit your own documentation of the function to us.</li> -<li>Don't group more than one issue (problem report or change request) - in one problem report. Instead, separate them into multiple - problem reports.</li> -<li>Always check the <a href="/FAQ.php">PHP FAQ</a> before submitting - bug reports.</li> -<li>Always search the bug database first for similar problem you are - experiencing. It might have already been reported and fixed. Or - it isn't a bug at all.</li> -<li>If PHP is crashing for you, please - <a href="bugs-generating-backtrace.php">generate a gdb backtrace</a> - and submit it with your bug report.</li> -<li>Never submit bug reports when it is obvious that there aren't nearly - enough details for us to solve it. For example, "phpinfo() dumps core" - makes a pretty useless bug report, unless you at least provide us - with the gdb backtrace, the switches you've compiled PHP with, etc.</li> -<li>Never add the php.ini file into the bug report.</li> -<li>Never add over 15 lines long example scripts into bug report. - If you are unable to create a short script that shows what the - problem is, put the long script into some place where it can - be accessed and add an URL for it into the report.</li> -<li>Never submit the same bug report more than once.</li> -<li>Always report bugs in the English language.</li> -<li>If you are trying to report bugs in PHP 4.0, please - go <a href="http://bugs.php.net/">here</a>.</li> + <li> + Remember the three basics: what you did, what you expected to happen, + and what happened. + </li> + <li> + When you provide code that demonstrates the problem, it should almost + never be more than ten lines long. Anything longer probably contains a + lot of code that has nothing to do with the problem, which just makes + it take longer to figure out the real problem. (But don't forget to make + sure that your code still demonstrates the bug you're reporting and + doesn't have some other problem because you've accidently trimmed out + something you thought wasn't important but was!) + </li> + <li> + If PHP is crashing, include a backtrace. Instructions for doing this + can be found <a href="bugs-generating-backtrace.php">here</a>. + </li> +</ul> + +<h2>Use English.</h2> + +<p>Yes, the PHP user and developer communities are global and include a great +many people who can speak a great many languages. But if you were to report a +bug in a language other than English, many (if not most) of the people who +would otherwise help you won't be able to. If you're worried about your English +skills making it difficult to describe the bug, you might try asking for help +on one of the <a href="http://www.php.net/support.php#local">non-English +mailing lists</a>.</p> + +<h2>Don't report bugs about old versions.</h2> + +<p>Every time a new version of PHP is released, hundreds of bugs are fixed. If +you're using a version of PHP that is more than two revisions older than the +latest version, you should upgrade to the latest version to make sure the bug +you are experiencing still exists.</p> + +<h2>Only report one problem in each bug report.</h2> + +<p>If you have encountered two bugs that don't appear to be related, create a +new bug report for each one. This makes it easier for different people to help +with the different bugs.</p> + +<h2>Don't report missing functions in the documentation.</h2> + +<p>We already know about it. We have tools that tell us when there are +functions that haven't been documented. There are <a +href="http://www.php.net/support.php">lots of places you can get help</a>.</p> + +<h2>Check out these other resources.</h2> + +<ul> + <li> + <a href="http://www.tuxedo.org/~esr/faqs/smart-questions.html">Eric + Raymond's How To Ask Questions The Smart Way</a> + </li> + <li> + <a href="http://www.mozilla.org/quality/bug-writing-guidelines.html">mozilla.org's + bug writing guidelines</a> + </li> + <li> + <a href="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html">Simon + Tatham's How to Report Bugs Effectively</a> + </li> </ul> <?php commonFooter(); ?>