diff options
Diffstat (limited to 'doc/src/sgml/html/bug-reporting.html')
| -rw-r--r-- | doc/src/sgml/html/bug-reporting.html | 248 |
1 files changed, 248 insertions, 0 deletions
diff --git a/doc/src/sgml/html/bug-reporting.html b/doc/src/sgml/html/bug-reporting.html new file mode 100644 index 0000000..e5eaa4d --- /dev/null +++ b/doc/src/sgml/html/bug-reporting.html @@ -0,0 +1,248 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!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 15.4 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</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="bug-reporting.html#id-1.3.8.5">5.1. Identifying Bugs</a></span></dt><dt><span class="sect2"><a href="bug-reporting.html#id-1.3.8.6">5.2. What to Report</a></span></dt><dt><span class="sect2"><a href="bug-reporting.html#id-1.3.8.7">5.3. Where to Report Bugs</a></span></dt></dl></div><p> + When you find a bug in <span class="productname">PostgreSQL</span> we want to + hear about it. Your bug reports play an important part in making + <span class="productname">PostgreSQL</span> more reliable because even the utmost + care cannot guarantee that every part of + <span class="productname">PostgreSQL</span> + will work on every platform under every circumstance. + </p><p> + The following suggestions are intended to assist you in forming bug reports + that can be handled in an effective fashion. No one is required to follow + them but doing so tends to be to everyone's advantage. + </p><p> + We cannot promise to fix every bug right away. If the bug is obvious, critical, + or affects a lot of users, chances are good that someone will look into it. It + could also happen that we tell you to update to a newer version to see if the + bug happens there. Or we might decide that the bug + cannot be fixed before some major rewrite we might be planning is done. Or + perhaps it is simply too hard and there are more important things on the agenda. + If you need help immediately, consider obtaining a commercial support contract. + </p><div class="sect2" id="id-1.3.8.5"><div class="titlepage"><div><div><h3 class="title">5.1. Identifying Bugs</h3></div></div></div><p> + Before you report a bug, please read and re-read the + documentation to verify that you can really do whatever it is you are + trying. If it is not clear from the documentation whether you can do + something or not, please report that too; it is a bug in the documentation. + If it turns out that a program does something different from what the + documentation says, that is a bug. That might include, but is not limited to, + the following circumstances: + + </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + A program terminates with a fatal signal or an operating system + error message that would point to a problem in the program. (A + counterexample might be a <span class="quote">“<span class="quote">disk full</span>”</span> message, + since you have to fix that yourself.) + </p></li><li class="listitem"><p> + A program produces the wrong output for any given input. + </p></li><li class="listitem"><p> + A program refuses to accept valid input (as defined in the documentation). + </p></li><li class="listitem"><p> + A program accepts invalid input without a notice or error message. + But keep in mind that your idea of invalid input might be our idea of + an extension or compatibility with traditional practice. + </p></li><li class="listitem"><p> + <span class="productname">PostgreSQL</span> fails to compile, build, or + install according to the instructions on supported platforms. + </p></li></ul></div><p> + + Here <span class="quote">“<span class="quote">program</span>”</span> refers to any executable, not only the backend process. + </p><p> + Being slow or resource-hogging is not necessarily a bug. Read the + documentation or ask on one of the mailing lists for help in tuning your + applications. Failing to comply to the <acronym class="acronym">SQL</acronym> standard is + not necessarily a bug either, unless compliance for the + specific feature is explicitly claimed. + </p><p> + Before you continue, check on the TODO list and in the FAQ to see if your bug is + already known. If you cannot decode the information on the TODO list, report your + problem. The least we can do is make the TODO list clearer. + </p></div><div class="sect2" id="id-1.3.8.6"><div class="titlepage"><div><div><h3 class="title">5.2. What to Report</h3></div></div></div><p> + The most important thing to remember about bug reporting is to state all + the facts and only facts. Do not speculate what you think went wrong, what + <span class="quote">“<span class="quote">it seemed to do</span>”</span>, or which part of the program has a fault. + If you are not familiar with the implementation you would probably guess + wrong and not help us a bit. And even if you are, educated explanations are + a great supplement to but no substitute for facts. If we are going to fix + the bug we still have to see it happen for ourselves first. + Reporting the bare facts + is relatively straightforward (you can probably copy and paste them from the + screen) but all too often important details are left out because someone + thought it does not matter or the report would be understood + anyway. + </p><p> + The following items should be contained in every bug report: + + </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + The exact sequence of steps <span class="emphasis"><em>from program + start-up</em></span> necessary to reproduce the problem. This + should be self-contained; it is not enough to send in a bare + <code class="command">SELECT</code> statement without the preceding + <code class="command">CREATE TABLE</code> and <code class="command">INSERT</code> + statements, if the output should depend on the data in the + tables. We do not have the time to reverse-engineer your + database schema, and if we are supposed to make up our own data + we would probably miss the problem. + </p><p> + The best format for a test case for SQL-related problems is a + file that can be run through the <span class="application">psql</span> + frontend that shows the problem. (Be sure to not have anything + in your <code class="filename">~/.psqlrc</code> start-up file.) An easy + way to create this file is to use <span class="application">pg_dump</span> + to dump out the table declarations and data needed to set the + scene, then add the problem query. You are encouraged to + minimize the size of your example, but this is not absolutely + necessary. If the bug is reproducible, we will find it either + way. + </p><p> + If your application uses some other client interface, such as <span class="application">PHP</span>, then + please try to isolate the offending queries. We will probably not set up a + web server to reproduce your problem. In any case remember to provide + the exact input files; do not guess that the problem happens for + <span class="quote">“<span class="quote">large files</span>”</span> or <span class="quote">“<span class="quote">midsize databases</span>”</span>, etc. since this + information is too inexact to be of use. + </p></li><li class="listitem"><p> + The output you got. Please do not say that it <span class="quote">“<span class="quote">didn't work</span>”</span> or + <span class="quote">“<span class="quote">crashed</span>”</span>. If there is an error message, + show it, even if you do not understand it. If the program terminates with + an operating system error, say which. If nothing at all happens, say so. + Even if the result of your test case is a program crash or otherwise obvious + it might not happen on our platform. The easiest thing is to copy the output + from the terminal, if possible. + </p><div class="note"><h3 class="title">Note</h3><p> + If you are reporting an error message, please obtain the most verbose + form of the message. In <span class="application">psql</span>, say <code class="literal">\set + VERBOSITY verbose</code> beforehand. If you are extracting the message + from the server log, set the run-time parameter + <a class="xref" href="runtime-config-logging.html#GUC-LOG-ERROR-VERBOSITY">log_error_verbosity</a> to <code class="literal">verbose</code> so that all + details are logged. + </p></div><div class="note"><h3 class="title">Note</h3><p> + In case of fatal errors, the error message reported by the client might + not contain all the information available. Please also look at the + log output of the database server. If you do not keep your server's log + output, this would be a good time to start doing so. + </p></div></li><li class="listitem"><p> + The output you expected is very important to state. If you just write + <span class="quote">“<span class="quote">This command gives me that output.</span>”</span> or <span class="quote">“<span class="quote">This is not + what I expected.</span>”</span>, we might run it ourselves, scan the output, and + think it looks OK and is exactly what we expected. We should not have to + spend the time to decode the exact semantics behind your commands. + Especially refrain from merely saying that <span class="quote">“<span class="quote">This is not what SQL says/Oracle + does.</span>”</span> Digging out the correct behavior from <acronym class="acronym">SQL</acronym> + is not a fun undertaking, nor do we all know how all the other relational + databases out there behave. (If your problem is a program crash, you can + obviously omit this item.) + </p></li><li class="listitem"><p> + Any command line options and other start-up options, including + any relevant environment variables or configuration files that + you changed from the default. Again, please provide exact + information. If you are using a prepackaged distribution that + starts the database server at boot time, you should try to find + out how that is done. + </p></li><li class="listitem"><p> + Anything you did at all differently from the installation + instructions. + </p></li><li class="listitem"><p> + The <span class="productname">PostgreSQL</span> version. You can run the command + <code class="literal">SELECT version();</code> to + find out the version of the server you are connected to. Most executable + programs also support a <code class="option">--version</code> option; at least + <code class="literal">postgres --version</code> and <code class="literal">psql --version</code> + should work. + If the function or the options do not exist then your version is + more than old enough to warrant an upgrade. + If you run a prepackaged version, such as RPMs, say so, including any + subversion the package might have. If you are talking about a Git + snapshot, mention that, including the commit hash. + </p><p> + If your version is older than 15.4 we will almost certainly + tell you to upgrade. There are many bug fixes and improvements + in each new release, so it is quite possible that a bug you have + encountered in an older release of <span class="productname">PostgreSQL</span> + has already been fixed. We can only provide limited support for + sites using older releases of <span class="productname">PostgreSQL</span>; if you + require more than we can provide, consider acquiring a + commercial support contract. + </p><p> + </p></li><li class="listitem"><p> + Platform information. This includes the kernel name and version, + C library, processor, memory information, and so on. In most + cases it is sufficient to report the vendor and version, but do + not assume everyone knows what exactly <span class="quote">“<span class="quote">Debian</span>”</span> + contains or that everyone runs on x86_64. If you have + installation problems then information about the toolchain on + your machine (compiler, <span class="application">make</span>, and so + on) is also necessary. + </p></li></ul></div><p> + + Do not be afraid if your bug report becomes rather lengthy. That is a fact of life. + It is better to report everything the first time than us having to squeeze the + facts out of you. On the other hand, if your input files are huge, it is + fair to ask first whether somebody is interested in looking into it. Here is + an <a class="ulink" href="https://www.chiark.greenend.org.uk/~sgtatham/bugs.html" target="_top">article</a> + that outlines some more tips on reporting bugs. + </p><p> + Do not spend all your time to figure out which changes in the input make + the problem go away. This will probably not help solving it. If it turns + out that the bug cannot be fixed right away, you will still have time to + find and share your work-around. Also, once again, do not waste your time + guessing why the bug exists. We will find that out soon enough. + </p><p> + When writing a bug report, please avoid confusing terminology. + The software package in total is called <span class="quote">“<span class="quote">PostgreSQL</span>”</span>, + sometimes <span class="quote">“<span class="quote">Postgres</span>”</span> for short. If you + are specifically talking about the backend process, mention that, do not + just say <span class="quote">“<span class="quote">PostgreSQL crashes</span>”</span>. A crash of a single + backend process is quite different from crash of the parent + <span class="quote">“<span class="quote">postgres</span>”</span> process; please don't say <span class="quote">“<span class="quote">the server + crashed</span>”</span> when you mean a single backend process went down, nor vice versa. + Also, client programs such as the interactive frontend <span class="quote">“<span class="quote"><span class="application">psql</span></span>”</span> + are completely separate from the backend. Please try to be specific + about whether the problem is on the client or server side. + </p></div><div class="sect2" id="id-1.3.8.7"><div class="titlepage"><div><div><h3 class="title">5.3. Where to Report Bugs</h3></div></div></div><p> + In general, send bug reports to the bug report mailing list at + <code class="email"><<a class="email" href="mailto:pgsql-bugs@lists.postgresql.org">pgsql-bugs@lists.postgresql.org</a>></code>. + You are requested to use a descriptive subject for your email + message, perhaps parts of the error message. + </p><p> + Another method is to fill in the bug report web-form available + at the project's + <a class="ulink" href="https://www.postgresql.org/" target="_top">web site</a>. + Entering a bug report this way causes it to be mailed to the + <code class="email"><<a class="email" href="mailto:pgsql-bugs@lists.postgresql.org">pgsql-bugs@lists.postgresql.org</a>></code> mailing list. + </p><p> + If your bug report has security implications and you'd prefer that it + not become immediately visible in public archives, don't send it to + <code class="literal">pgsql-bugs</code>. Security issues can be + reported privately to <code class="email"><<a class="email" href="mailto:security@postgresql.org">security@postgresql.org</a>></code>. + </p><p> + Do not send bug reports to any of the user mailing lists, such as + <code class="email"><<a class="email" href="mailto:pgsql-sql@lists.postgresql.org">pgsql-sql@lists.postgresql.org</a>></code> or + <code class="email"><<a class="email" href="mailto:pgsql-general@lists.postgresql.org">pgsql-general@lists.postgresql.org</a>></code>. + These mailing lists are for answering + user questions, and their subscribers normally do not wish to receive + bug reports. More importantly, they are unlikely to fix them. + </p><p> + Also, please do <span class="emphasis"><em>not</em></span> send reports to + the developers' mailing list <code class="email"><<a class="email" href="mailto:pgsql-hackers@lists.postgresql.org">pgsql-hackers@lists.postgresql.org</a>></code>. + This list is for discussing the + development of <span class="productname">PostgreSQL</span>, and it would be nice + if we could keep the bug reports separate. We might choose to take up a + discussion about your bug report on <code class="literal">pgsql-hackers</code>, + if the problem needs more review. + </p><p> + If you have a problem with the documentation, the best place to report it + 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>. + Please be specific about what part of the documentation you are unhappy + with. + </p><p> + If your bug is a portability problem on a non-supported platform, + send mail to <code class="email"><<a class="email" href="mailto:pgsql-hackers@lists.postgresql.org">pgsql-hackers@lists.postgresql.org</a>></code>, + so we (and you) can work on + porting <span class="productname">PostgreSQL</span> to your platform. + </p><div class="note"><h3 class="title">Note</h3><p> + Due to the unfortunate amount of spam going around, all of the above + lists will be moderated unless you are subscribed. That means there + will be some delay before the email is delivered. If you wish to subscribe + to the lists, please visit + <a class="ulink" href="https://lists.postgresql.org/" target="_top">https://lists.postgresql.org/</a> for instructions. + </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 15.4 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Part I. Tutorial</td></tr></table></div></body></html>
\ No newline at end of file |