1<?php $this->extends('layout.php', ['title' => 'How to Report a Bug']) ?> 2 3<?php $this->start('content') ?> 4 5<h1>How to Report a Bug</h1> 6 7<p>There is a large number of PHP users. There is a much smaller number of people 8who actually develop the PHP language and extensions. There is an even smaller 9number of people who actively fix bugs reported by users.</p> 10 11<p>What does this mean for you, an aspiring bug reporter? In order to catch the 12eye of one of these few stalwart <b>volunteers</b>, you'll need to take to 13heart a few tips on how to report a bug so that they can and will help you.</p> 14 15<p>Take special note of that word in bold above. The people who are going to 16help you with a bug you report are <b>volunteers</b>. Not only are you not 17paying them to help you, but nobody else is either. So, to paraphrase the 18immortal words of <a href="https://www.imdb.com/title/tt0096928/">Bill and Ted</a>, 19<b>"be excellent to them"</b>.</p> 20 21<p>Beyond that golden rule, what follows are some additional tips on ways to 22make your bug report better so that someone will be able to help you.</p> 23 24<h2>The basics: what you did, what you wanted to happen, and what actually 25happened.</h2> 26 27<p>Those are the three basic elements of a bug report. You need to tell us 28exactly what you did (for example, "My script calls 29make_happy_meal('hamburger','onion rings')") , what you expected to have happen 30(to continue the example, "I expected PHP to serve me a happy meal with a 31hamburger and onion rings"), and what actually happened ("It gave me a happy 32meal with french fries.").</p> 33 34<p>Yes, the example is silly. But if your bug report simply said "The 35make_happy_meal function doesn't work," we wouldn't be able to say "That's 36because you can't have onion rings in a happy meal, you can only have french 37fries or curly fries." By telling us what you asked for, what you expected to 38get, and what you actually got, we don't have to guess.</p> 39 40<h2>Always search the bug database first.</h2> 41 42<p>Advice is so good, we'll repeat it twice. Always <a 43href="/search.php">search</a> the bug database first. As we said above, there's 44a lot of users of PHP. The odds are good that if you've found a problem, 45someone else has found it, too. If you spend a few minutes of your time making 46sure that you're not filing a duplicate bug, that's a few more minutes someone 47can spend helping to fix that bug rather than sorting out duplicate bug 48reports.</p> 49 50<h2>If you don't understand an error message, ask for help.</h2> 51 52<p>Don't report an error message you don't understand as a bug. There are <a 53href="https://php.net/support.php">a lot of places you can ask for help</a> 54in understanding what is going on before you can claim that an error message 55you do not understand is a bug.</p> 56 57<p>(Now, once you've understood the error message, and have a good suggestion 58for a way to make the error message more clear, you might consider reporting it 59as a feature request.)</p> 60 61<h2>Be brief, but don't leave any important details out.</h2> 62 63<p>This is a fine line to walk. But there are some general guidelines:</p> 64<ul> 65 <li> 66 Remember the three basics: what you did, what you expected to happen, 67 and what happened. 68 </li> 69 <li> 70 When you provide code that demonstrates the problem, it should almost 71 never be more than ten lines long. Anything longer probably contains a 72 lot of code that has nothing to do with the problem, which just increases 73 the time to figure out the real problem. (But don't forget to make 74 sure that your code still demonstrates the bug you're reporting and 75 doesn't have some other problem because you've accidentally trimmed out 76 something you thought wasn't important but was!) 77 </li> 78 <li> 79 If PHP is crashing, include a backtrace. Instructions for doing this 80 can be found <a href="/bugs-generating-backtrace.php">here for *NIX users</a> and 81 <a href="/bugs-generating-backtrace-win32.php">here for Windows users</a>. 82 </li> 83 <li> 84 <a href="http://valgrind.org">Valgrind</a> log can be also very useful. 85 See <a href="/bugs-getting-valgrind-log.php">instructions how to generate it</a>. 86 </li> 87</ul> 88 89<h2>Use English.</h2> 90 91<p>Yes, the PHP user and developer communities are global and include a great 92many people who can speak a great many languages. But if you were to report a 93bug in a language other than English, many (if not most) of the people who 94would otherwise help you won't be able to. If you're worried about your English 95skills making it difficult to describe the bug, you might try asking for help 96on one of the <a href="https://php.net/support.php#local">non-English 97mailing lists</a>.</p> 98 99<h2>Don't report bugs about old versions.</h2> 100 101<p>Every time a new version of PHP is released, dozens of bugs are fixed. If 102you're using a version of PHP that is more than two revisions older than the 103latest version, you should upgrade to the latest version to make sure the bug 104you are experiencing still exists.</p> 105 106<p>Note that PHP branches which are no longer <a 107href="https://php.net/supported-versions.php">actively supported</a> will 108receive fixes for critical security issues only. So please do not report 109non-security related bugs which do not affect any actively supported PHP 110branch.</p> 111 112<h2>Only report one problem in each bug report.</h2> 113 114<p>If you have encountered two bugs that don't appear to be related, create a 115new bug report for each one. This makes it easier for different people to help 116with the different bugs.</p> 117 118<h2>Check out these other resources.</h2> 119 120<ul> 121 <li> 122 Eric Raymond's and Rick Moen's 123 <a href="http://www.catb.org/~esr/faqs/smart-questions.html">How 124 To Ask Questions The Smart Way</a> 125 </li> 126 <li> 127 mozilla.org's 128 <a href="https://developer.mozilla.org/en-US/docs/Mozilla/QA/Bug_writing_guidelines">bug 129 writing guidelines</a> 130 </li> 131 <li> 132 Simon Tatham's <a href="https://www.chiark.greenend.org.uk/~sgtatham/bugs.html">How 133 to Report Bugs Effectively</a> 134 </li> 135</ul> 136 137<?php $this->end('content') ?> 138