diff options
Diffstat (limited to 'doc/src/sgml/problems.sgml')
| -rw-r--r-- | doc/src/sgml/problems.sgml | 362 |
1 files changed, 362 insertions, 0 deletions
diff --git a/doc/src/sgml/problems.sgml b/doc/src/sgml/problems.sgml new file mode 100644 index 0000000..cf43262 --- /dev/null +++ b/doc/src/sgml/problems.sgml @@ -0,0 +1,362 @@ +<!-- doc/src/sgml/problems.sgml --> + +<sect1 id="bug-reporting"> + <title>Bug Reporting Guidelines</title> + + <para> + When you find a bug in <productname>PostgreSQL</productname> we want to + hear about it. Your bug reports play an important part in making + <productname>PostgreSQL</productname> more reliable because even the utmost + care cannot guarantee that every part of + <productname>PostgreSQL</productname> + will work on every platform under every circumstance. + </para> + + <para> + 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. + </para> + + <para> + 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. + </para> + + <sect2> + <title>Identifying Bugs</title> + + <para> + 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: + + <itemizedlist> + <listitem> + <para> + 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 <quote>disk full</quote> message, + since you have to fix that yourself.) + </para> + </listitem> + + <listitem> + <para> + A program produces the wrong output for any given input. + </para> + </listitem> + + <listitem> + <para> + A program refuses to accept valid input (as defined in the documentation). + </para> + </listitem> + + <listitem> + <para> + 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. + </para> + </listitem> + + <listitem> + <para> + <productname>PostgreSQL</productname> fails to compile, build, or + install according to the instructions on supported platforms. + </para> + </listitem> + </itemizedlist> + + Here <quote>program</quote> refers to any executable, not only the backend process. + </para> + + <para> + 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>SQL</acronym> standard is + not necessarily a bug either, unless compliance for the + specific feature is explicitly claimed. + </para> + + <para> + 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. + </para> + </sect2> + + <sect2> + <title>What to Report</title> + + <para> + 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 + <quote>it seemed to do</quote>, 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. + </para> + + <para> + The following items should be contained in every bug report: + + <itemizedlist> + <listitem> + <para> + The exact sequence of steps <emphasis>from program + start-up</emphasis> necessary to reproduce the problem. This + should be self-contained; it is not enough to send in a bare + <command>SELECT</command> statement without the preceding + <command>CREATE TABLE</command> and <command>INSERT</command> + 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. + </para> + + <para> + The best format for a test case for SQL-related problems is a + file that can be run through the <application>psql</application> + frontend that shows the problem. (Be sure to not have anything + in your <filename>~/.psqlrc</filename> start-up file.) An easy + way to create this file is to use <application>pg_dump</application> + 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. + </para> + + <para> + If your application uses some other client interface, such as <application>PHP</application>, 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 + <quote>large files</quote> or <quote>midsize databases</quote>, etc. since this + information is too inexact to be of use. + </para> + </listitem> + + <listitem> + <para> + The output you got. Please do not say that it <quote>didn't work</quote> or + <quote>crashed</quote>. 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. + </para> + <note> + <para> + If you are reporting an error message, please obtain the most verbose + form of the message. In <application>psql</application>, say <literal>\set + VERBOSITY verbose</literal> beforehand. If you are extracting the message + from the server log, set the run-time parameter + <xref linkend="guc-log-error-verbosity"/> to <literal>verbose</literal> so that all + details are logged. + </para> + </note> + <note> + <para> + 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. + </para> + </note> + </listitem> + + <listitem> + <para> + The output you expected is very important to state. If you just write + <quote>This command gives me that output.</quote> or <quote>This is not + what I expected.</quote>, 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 <quote>This is not what SQL says/Oracle + does.</quote> Digging out the correct behavior from <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.) + </para> + </listitem> + + <listitem> + <para> + 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. + </para> + </listitem> + + <listitem> + <para> + Anything you did at all differently from the installation + instructions. + </para> + </listitem> + + <listitem> + <para> + The <productname>PostgreSQL</productname> version. You can run the command + <literal>SELECT version();</literal> to + find out the version of the server you are connected to. Most executable + programs also support a <option>--version</option> option; at least + <literal>postgres --version</literal> and <literal>psql --version</literal> + 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. + </para> + + <para> + If your version is older than &version; 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 <productname>PostgreSQL</productname> + has already been fixed. We can only provide limited support for + sites using older releases of <productname>PostgreSQL</productname>; if you + require more than we can provide, consider acquiring a + commercial support contract. + </para> + <para> + </para> + </listitem> + + <listitem> + <para> + 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 <quote>Debian</quote> + contains or that everyone runs on x86_64. If you have + installation problems then information about the toolchain on + your machine (compiler, <application>make</application>, and so + on) is also necessary. + </para> + </listitem> + </itemizedlist> + + 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 <ulink url="https://www.chiark.greenend.org.uk/~sgtatham/bugs.html">article</ulink> + that outlines some more tips on reporting bugs. + </para> + + <para> + 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. + </para> + + <para> + When writing a bug report, please avoid confusing terminology. + The software package in total is called <quote>PostgreSQL</quote>, + sometimes <quote>Postgres</quote> for short. If you + are specifically talking about the backend process, mention that, do not + just say <quote>PostgreSQL crashes</quote>. A crash of a single + backend process is quite different from crash of the parent + <quote>postgres</quote> process; please don't say <quote>the server + crashed</quote> when you mean a single backend process went down, nor vice versa. + Also, client programs such as the interactive frontend <quote><application>psql</application></quote> + are completely separate from the backend. Please try to be specific + about whether the problem is on the client or server side. + </para> + </sect2> + + <sect2> + <title>Where to Report Bugs</title> + + <para> + In general, send bug reports to the bug report mailing list at + <email>pgsql-bugs@lists.postgresql.org</email>. + You are requested to use a descriptive subject for your email + message, perhaps parts of the error message. + </para> + + <para> + Another method is to fill in the bug report web-form available + at the project's + <ulink url="https://www.postgresql.org/">web site</ulink>. + Entering a bug report this way causes it to be mailed to the + <email>pgsql-bugs@lists.postgresql.org</email> mailing list. + </para> + + <para> + 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 + <literal>pgsql-bugs</literal>. Security issues can be + reported privately to <email>security@postgresql.org</email>. + </para> + + <para> + Do not send bug reports to any of the user mailing lists, such as + <email>pgsql-sql@lists.postgresql.org</email> or + <email>pgsql-general@lists.postgresql.org</email>. + 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. + </para> + + <para> + Also, please do <emphasis>not</emphasis> send reports to + the developers' mailing list <email>pgsql-hackers@lists.postgresql.org</email>. + This list is for discussing the + development of <productname>PostgreSQL</productname>, 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 <literal>pgsql-hackers</literal>, + if the problem needs more review. + </para> + + <para> + If you have a problem with the documentation, the best place to report it + is the documentation mailing list <email>pgsql-docs@lists.postgresql.org</email>. + Please be specific about what part of the documentation you are unhappy + with. + </para> + + <para> + If your bug is a portability problem on a non-supported platform, + send mail to <email>pgsql-hackers@lists.postgresql.org</email>, + so we (and you) can work on + porting <productname>PostgreSQL</productname> to your platform. + </para> + + <note> + <para> + 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 + <ulink url="https://lists.postgresql.org/"></ulink> for instructions. + </para> + </note> + </sect2> +</sect1> |