Team Ai
Datasetpublic

codekingpro/portable-devtools

sourceHugging Faceupdated 5mo agoView on Hugging Face
1likes15kdownloads
bug-reporting.html248 linesDownload Raw Back to html
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">&lt;<a class="email" href="mailto:pgsql-bugs@lists.postgresql.org">pgsql-bugs@lists.postgresql.org</a>&gt;</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">&lt;<a class="email" href="mailto:pgsql-bugs@lists.postgresql.org">pgsql-bugs@lists.postgresql.org</a>&gt;</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">&lt;<a class="email" href="mailto:security@postgresql.org">security@postgresql.org</a>&gt;</code>.217  </p><p>218   Do not send bug reports to any of the user mailing lists, such as219   <code class="email">&lt;<a class="email" href="mailto:pgsql-sql@lists.postgresql.org">pgsql-sql@lists.postgresql.org</a>&gt;</code> or220   <code class="email">&lt;<a class="email" href="mailto:pgsql-general@lists.postgresql.org">pgsql-general@lists.postgresql.org</a>&gt;</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">&lt;<a class="email" href="mailto:pgsql-hackers@lists.postgresql.org">pgsql-hackers@lists.postgresql.org</a>&gt;</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">&lt;<a class="email" href="mailto:pgsql-docs@lists.postgresql.org">pgsql-docs@lists.postgresql.org</a>&gt;</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">&lt;<a class="email" href="mailto:pgsql-hackers@lists.postgresql.org">pgsql-hackers@lists.postgresql.org</a>&gt;</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>
codekingpro/portable-devtools · Team Ai