codekingpro/portable-devtools
115k
1<?xml version="1.0" encoding="UTF-8" standalone="no"?>2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>5. Bug Reporting Guidelines</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="resources.html" title="4. Further Information" /><link rel="next" href="tutorial.html" title="Part I. Tutorial" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">5. Bug Reporting Guidelines</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="resources.html" title="4. Further Information">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="preface.html" title="Preface">Up</a></td><th width="60%" align="center">Preface</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="tutorial.html" title="Part I. Tutorial">Next</a></td></tr></table><hr /></div><div class="sect1" id="BUG-REPORTING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">5. Bug Reporting Guidelines <a href="#BUG-REPORTING" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="bug-reporting.html#BUG-REPORTING-IDENTIFYING-BUGS">5.1. Identifying Bugs</a></span></dt><dt><span class="sect2"><a href="bug-reporting.html#BUG-REPORTING-WHAT-TO-REPORT">5.2. What to Report</a></span></dt><dt><span class="sect2"><a href="bug-reporting.html#BUG-REPORTING-WHERE-TO-REPORT-BUGS">5.3. Where to Report Bugs</a></span></dt></dl></div><p>3 When you find a bug in <span class="productname">PostgreSQL</span> we want to4 hear about it. Your bug reports play an important part in making5 <span class="productname">PostgreSQL</span> more reliable because even the utmost6 care cannot guarantee that every part of7 <span class="productname">PostgreSQL</span>8 will work on every platform under every circumstance.9 </p><p>10 The following suggestions are intended to assist you in forming bug reports11 that can be handled in an effective fashion. No one is required to follow12 them but doing so tends to be to everyone's advantage.13 </p><p>14 We cannot promise to fix every bug right away. If the bug is obvious, critical,15 or affects a lot of users, chances are good that someone will look into it. It16 could also happen that we tell you to update to a newer version to see if the17 bug happens there. Or we might decide that the bug18 cannot be fixed before some major rewrite we might be planning is done. Or19 perhaps it is simply too hard and there are more important things on the agenda.20 If you need help immediately, consider obtaining a commercial support contract.21 </p><div class="sect2" id="BUG-REPORTING-IDENTIFYING-BUGS"><div class="titlepage"><div><div><h3 class="title">5.1. Identifying Bugs <a href="#BUG-REPORTING-IDENTIFYING-BUGS" class="id_link">#</a></h3></div></div></div><p>22 Before you report a bug, please read and re-read the23 documentation to verify that you can really do whatever it is you are24 trying. If it is not clear from the documentation whether you can do25 something or not, please report that too; it is a bug in the documentation.26 If it turns out that a program does something different from what the27 documentation says, that is a bug. That might include, but is not limited to,28 the following circumstances:29 30 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>31 A program terminates with a fatal signal or an operating system32 error message that would point to a problem in the program. (A33 counterexample might be a <span class="quote">“<span class="quote">disk full</span>”</span> message,34 since you have to fix that yourself.)35 </p></li><li class="listitem"><p>36 A program produces the wrong output for any given input.37 </p></li><li class="listitem"><p>38 A program refuses to accept valid input (as defined in the documentation).39 </p></li><li class="listitem"><p>40 A program accepts invalid input without a notice or error message.41 But keep in mind that your idea of invalid input might be our idea of42 an extension or compatibility with traditional practice.43 </p></li><li class="listitem"><p>44 <span class="productname">PostgreSQL</span> fails to compile, build, or45 install according to the instructions on supported platforms.46 </p></li></ul></div><p>47 48 Here <span class="quote">“<span class="quote">program</span>”</span> refers to any executable, not only the backend process.49 </p><p>50 Being slow or resource-hogging is not necessarily a bug. Read the51 documentation or ask on one of the mailing lists for help in tuning your52 applications. Failing to comply to the <acronym class="acronym">SQL</acronym> standard is53 not necessarily a bug either, unless compliance for the54 specific feature is explicitly claimed.55 </p><p>56 Before you continue, check on the TODO list and in the FAQ to see if your bug is57 already known. If you cannot decode the information on the TODO list, report your58 problem. The least we can do is make the TODO list clearer.59 </p></div><div class="sect2" id="BUG-REPORTING-WHAT-TO-REPORT"><div class="titlepage"><div><div><h3 class="title">5.2. What to Report <a href="#BUG-REPORTING-WHAT-TO-REPORT" class="id_link">#</a></h3></div></div></div><p>60 The most important thing to remember about bug reporting is to state all61 the facts and only facts. Do not speculate what you think went wrong, what62 <span class="quote">“<span class="quote">it seemed to do</span>”</span>, or which part of the program has a fault.63 If you are not familiar with the implementation you would probably guess64 wrong and not help us a bit. And even if you are, educated explanations are65 a great supplement to but no substitute for facts. If we are going to fix66 the bug we still have to see it happen for ourselves first.67 Reporting the bare facts68 is relatively straightforward (you can probably copy and paste them from the69 screen) but all too often important details are left out because someone70 thought it does not matter or the report would be understood71 anyway.72 </p><p>73 The following items should be contained in every bug report:74 75 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>76 The exact sequence of steps <span class="emphasis"><em>from program77 start-up</em></span> necessary to reproduce the problem. This78 should be self-contained; it is not enough to send in a bare79 <code class="command">SELECT</code> statement without the preceding80 <code class="command">CREATE TABLE</code> and <code class="command">INSERT</code>81 statements, if the output should depend on the data in the82 tables. We do not have the time to reverse-engineer your83 database schema, and if we are supposed to make up our own data84 we would probably miss the problem.85 </p><p>86 The best format for a test case for SQL-related problems is a87 file that can be run through the <span class="application">psql</span>88 frontend that shows the problem. (Be sure to not have anything89 in your <code class="filename">~/.psqlrc</code> start-up file.) An easy90 way to create this file is to use <span class="application">pg_dump</span>91 to dump out the table declarations and data needed to set the92 scene, then add the problem query. You are encouraged to93 minimize the size of your example, but this is not absolutely94 necessary. If the bug is reproducible, we will find it either95 way.96 </p><p>97 If your application uses some other client interface, such as <span class="application">PHP</span>, then98 please try to isolate the offending queries. We will probably not set up a99 web server to reproduce your problem. In any case remember to provide100 the exact input files; do not guess that the problem happens for101 <span class="quote">“<span class="quote">large files</span>”</span> or <span class="quote">“<span class="quote">midsize databases</span>”</span>, etc. since this102 information is too inexact to be of use.103 </p></li><li class="listitem"><p>104 The output you got. Please do not say that it <span class="quote">“<span class="quote">didn't work</span>”</span> or105 <span class="quote">“<span class="quote">crashed</span>”</span>. If there is an error message,106 show it, even if you do not understand it. If the program terminates with107 an operating system error, say which. If nothing at all happens, say so.108 Even if the result of your test case is a program crash or otherwise obvious109 it might not happen on our platform. The easiest thing is to copy the output110 from the terminal, if possible.111 </p><div class="note"><h3 class="title">Note</h3><p>112 If you are reporting an error message, please obtain the most verbose113 form of the message. In <span class="application">psql</span>, say <code class="literal">\set114 VERBOSITY verbose</code> beforehand. If you are extracting the message115 from the server log, set the run-time parameter116 <a class="xref" href="runtime-config-logging.html#GUC-LOG-ERROR-VERBOSITY">log_error_verbosity</a> to <code class="literal">verbose</code> so that all117 details are logged.118 </p></div><div class="note"><h3 class="title">Note</h3><p>119 In case of fatal errors, the error message reported by the client might120 not contain all the information available. Please also look at the121 log output of the database server. If you do not keep your server's log122 output, this would be a good time to start doing so.123 </p></div></li><li class="listitem"><p>124 The output you expected is very important to state. If you just write125 <span class="quote">“<span class="quote">This command gives me that output.</span>”</span> or <span class="quote">“<span class="quote">This is not126 what I expected.</span>”</span>, we might run it ourselves, scan the output, and127 think it looks OK and is exactly what we expected. We should not have to128 spend the time to decode the exact semantics behind your commands.129 Especially refrain from merely saying that <span class="quote">“<span class="quote">This is not what SQL says/Oracle130 does.</span>”</span> Digging out the correct behavior from <acronym class="acronym">SQL</acronym>131 is not a fun undertaking, nor do we all know how all the other relational132 databases out there behave. (If your problem is a program crash, you can133 obviously omit this item.)134 </p></li><li class="listitem"><p>135 Any command line options and other start-up options, including136 any relevant environment variables or configuration files that137 you changed from the default. Again, please provide exact138 information. If you are using a prepackaged distribution that139 starts the database server at boot time, you should try to find140 out how that is done.141 </p></li><li class="listitem"><p>142 Anything you did at all differently from the installation143 instructions.144 </p></li><li class="listitem"><p>145 The <span class="productname">PostgreSQL</span> version. You can run the command146 <code class="literal">SELECT version();</code> to147 find out the version of the server you are connected to. Most executable148 programs also support a <code class="option">--version</code> option; at least149 <code class="literal">postgres --version</code> and <code class="literal">psql --version</code>150 should work.151 If the function or the options do not exist then your version is152 more than old enough to warrant an upgrade.153 If you run a prepackaged version, such as RPMs, say so, including any154 subversion the package might have. If you are talking about a Git155 snapshot, mention that, including the commit hash.156 </p><p>157 If your version is older than 16.3 we will almost certainly158 tell you to upgrade. There are many bug fixes and improvements159 in each new release, so it is quite possible that a bug you have160 encountered in an older release of <span class="productname">PostgreSQL</span>161 has already been fixed. We can only provide limited support for162 sites using older releases of <span class="productname">PostgreSQL</span>; if you163 require more than we can provide, consider acquiring a164 commercial support contract.165 </p><p>166 </p></li><li class="listitem"><p>167 Platform information. This includes the kernel name and version,168 C library, processor, memory information, and so on. In most169 cases it is sufficient to report the vendor and version, but do170 not assume everyone knows what exactly <span class="quote">“<span class="quote">Debian</span>”</span>171 contains or that everyone runs on x86_64. If you have172 installation problems then information about the toolchain on173 your machine (compiler, <span class="application">make</span>, and so174 on) is also necessary.175 </p></li></ul></div><p>176 177 Do not be afraid if your bug report becomes rather lengthy. That is a fact of life.178 It is better to report everything the first time than us having to squeeze the179 facts out of you. On the other hand, if your input files are huge, it is180 fair to ask first whether somebody is interested in looking into it. Here is181 an <a class="ulink" href="https://www.chiark.greenend.org.uk/~sgtatham/bugs.html" target="_top">article</a>182 that outlines some more tips on reporting bugs.183 </p><p>184 Do not spend all your time to figure out which changes in the input make185 the problem go away. This will probably not help solving it. If it turns186 out that the bug cannot be fixed right away, you will still have time to187 find and share your work-around. Also, once again, do not waste your time188 guessing why the bug exists. We will find that out soon enough.189 </p><p>190 When writing a bug report, please avoid confusing terminology.191 The software package in total is called <span class="quote">“<span class="quote">PostgreSQL</span>”</span>,192 sometimes <span class="quote">“<span class="quote">Postgres</span>”</span> for short. If you193 are specifically talking about the backend process, mention that, do not194 just say <span class="quote">“<span class="quote">PostgreSQL crashes</span>”</span>. A crash of a single195 backend process is quite different from crash of the parent196 <span class="quote">“<span class="quote">postgres</span>”</span> process; please don't say <span class="quote">“<span class="quote">the server197 crashed</span>”</span> when you mean a single backend process went down, nor vice versa.198 Also, client programs such as the interactive frontend <span class="quote">“<span class="quote"><span class="application">psql</span></span>”</span>199 are completely separate from the backend. Please try to be specific200 about whether the problem is on the client or server side.201 </p></div><div class="sect2" id="BUG-REPORTING-WHERE-TO-REPORT-BUGS"><div class="titlepage"><div><div><h3 class="title">5.3. Where to Report Bugs <a href="#BUG-REPORTING-WHERE-TO-REPORT-BUGS" class="id_link">#</a></h3></div></div></div><p>202 In general, send bug reports to the bug report mailing list at203 <code class="email"><<a class="email" href="mailto:pgsql-bugs@lists.postgresql.org">pgsql-bugs@lists.postgresql.org</a>></code>.204 You are requested to use a descriptive subject for your email205 message, perhaps parts of the error message.206 </p><p>207 Another method is to fill in the bug report web-form available208 at the project's209 <a class="ulink" href="https://www.postgresql.org/" target="_top">web site</a>.210 Entering a bug report this way causes it to be mailed to the211 <code class="email"><<a class="email" href="mailto:pgsql-bugs@lists.postgresql.org">pgsql-bugs@lists.postgresql.org</a>></code> mailing list.212 </p><p>213 If your bug report has security implications and you'd prefer that it214 not become immediately visible in public archives, don't send it to215 <code class="literal">pgsql-bugs</code>. Security issues can be216 reported privately to <code class="email"><<a class="email" href="mailto:security@postgresql.org">security@postgresql.org</a>></code>.217 </p><p>218 Do not send bug reports to any of the user mailing lists, such as219 <code class="email"><<a class="email" href="mailto:pgsql-sql@lists.postgresql.org">pgsql-sql@lists.postgresql.org</a>></code> or220 <code class="email"><<a class="email" href="mailto:pgsql-general@lists.postgresql.org">pgsql-general@lists.postgresql.org</a>></code>.221 These mailing lists are for answering222 user questions, and their subscribers normally do not wish to receive223 bug reports. More importantly, they are unlikely to fix them.224 </p><p>225 Also, please do <span class="emphasis"><em>not</em></span> send reports to226 the developers' mailing list <code class="email"><<a class="email" href="mailto:pgsql-hackers@lists.postgresql.org">pgsql-hackers@lists.postgresql.org</a>></code>.227 This list is for discussing the228 development of <span class="productname">PostgreSQL</span>, and it would be nice229 if we could keep the bug reports separate. We might choose to take up a230 discussion about your bug report on <code class="literal">pgsql-hackers</code>,231 if the problem needs more review.232 </p><p>233 If you have a problem with the documentation, the best place to report it234 is the documentation mailing list <code class="email"><<a class="email" href="mailto:pgsql-docs@lists.postgresql.org">pgsql-docs@lists.postgresql.org</a>></code>.235 Please be specific about what part of the documentation you are unhappy236 with.237 </p><p>238 If your bug is a portability problem on a non-supported platform,239 send mail to <code class="email"><<a class="email" href="mailto:pgsql-hackers@lists.postgresql.org">pgsql-hackers@lists.postgresql.org</a>></code>,240 so we (and you) can work on241 porting <span class="productname">PostgreSQL</span> to your platform.242 </p><div class="note"><h3 class="title">Note</h3><p>243 Due to the unfortunate amount of spam going around, all of the above244 lists will be moderated unless you are subscribed. That means there245 will be some delay before the email is delivered. If you wish to subscribe246 to the lists, please visit247 <a class="ulink" href="https://lists.postgresql.org/" target="_top">https://lists.postgresql.org/</a> for instructions.248 </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="resources.html" title="4. Further Information">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="preface.html" title="Preface">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial.html" title="Part I. Tutorial">Next</a></td></tr><tr><td width="40%" align="left" valign="top">4. Further Information </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Part I. Tutorial</td></tr></table></div></body></html>