From 0f17e3faab6bcc5321ac65691a00316b194239f2 Mon Sep 17 00:00:00 2001 From: Peter Eisentraut <peter_e@gmx.net> Date: Fri, 10 Mar 2000 22:32:59 +0000 Subject: [PATCH] Okay, this time I *really* added the bug reporting guidelines. --- doc/src/sgml/bug-reporting.sgml | 296 ++++++++++++++++++++++++++++++++ 1 file changed, 296 insertions(+) create mode 100644 doc/src/sgml/bug-reporting.sgml diff --git a/doc/src/sgml/bug-reporting.sgml b/doc/src/sgml/bug-reporting.sgml new file mode 100644 index 00000000000..2360fe64a33 --- /dev/null +++ b/doc/src/sgml/bug-reporting.sgml @@ -0,0 +1,296 @@ +<Sect1> + <title>Bug Reporting Guidelines</title> + + <para> + When you encounter a bug in <productname>PostgreSQL</productname> we want to + hear about it. Your bug reports are an important part in making + <productname>PostgreSQL</productname> more reliable because even the utmost + care cannot guarantee that every part of PostgreSQL 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 it 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's 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 ask <quote>Is this a bug?</quote>, 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's a bug in the documentation. + If it turns out that the program does something different from what the + documentation says, that's 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 (for + example not <quote>disk full</quote>). + </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. + </para> + </listitem> + + <listitem> + <para> + A program accepts invalid input without a notice or error message. + </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 server. + </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 <acronym>SQL</acronym> is not a bug 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 can't 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 doesn't matter or the report would <quote>ring a bell</quote> + anyway. + </para> + + <para> + The following items should be contained in every bug report: + + <itemizedlist> + <listitem> + <para> + The exact sequence of steps <emphasis>from program startup</emphasis> + necessary to reproduce the problem. This should be self-contained; + it is not enough to send in a bare select statement without the + preceeding create table and insert statements, if the output should + depend on the data in the tables. We do not have the time + to decode your database schema, and if we are supposed to make up + our own data we would probably miss the problem. + The best format for a test case for + query-language 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> startup file.) You are encouraged to + minimize the size of your example, but this is not absolutely necessary. + If the bug is reproduceable, we'll find it either way. + </para> + <para> + If your application uses some other client interface, such as PHP, then + please try to isolate the offending queries. We probably won't 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>mid-size databases</quote>, etc. + </para> + </listitem> + + <listitem> + <para> + The output you got. Please do not say that it <quote>didn't work</quote> or + <quote>failed</quote>. If there is an error message, + show it, even if you don't 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> + In case of fatal errors, the error message provided by the client might + not contain all the information available. In that case, also look at the + output of the database server. If you do not keep your server 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 okay and is exactly what we expected. We shouldn't 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 startup options, including concerned + environment variables or configuration files that you changed from the + default. Again, be exact. If you are using a pre-packaged + 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 PostgreSQL version. You can run the command + <literal>SELECT version();</literal> to + find out. If this function does not exist, say so, then we know that + your version is old enough. If you can't start up the server or a + client, look into the README file in the source directory or at the + name of your distribution file or package name. If your version is older + than 6.5 we will almost certainly tell you to upgrade. There are tons + of bugs in old versions, that's why we write new ones. + </para> + <para> + If you run a pre-packaged version, such as RPMs, say so, including any + subversion the package may have. If you are talking about a CVS + snapshot, mention that, including its date and time. + </para> + </listitem> + + <listitem> + <para> + Platform information. This includes the kernel name and version, C library, + processor, memory information. 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 Pentiums. If + you have installation problems information about compilers, make, etc. + is also necessary. + </para> + </listitem> + </itemizedlist> + + Do not be afraid if your bug report becomes rather lengthy. That is a fact of life. + It's 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. + </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 can't 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'll find that out soon enough. + </para> + + <para> + When writing a bug report, please choose non-confusing terminology. + The software package as such is called <quote>PostgreSQL</quote>, + sometimes <quote>Postgres</quote> for short. (Sometimes + the abbreviation <quote>Pgsql</quote> is used but don't do that.) When you + are specifically talking about the backend server, mention that, don't + just say <quote>Postgres crashes</quote>. The interactive frontend is called + <quote>psql</quote> and is for all intends and purposes completely separate + from the backend. + </para> + </Sect2> + + <Sect2> + <title>Where to report bugs</title> + + <para> + In general, send bug reports to <pgsql-bugs@postgresql.org>. You are + invited to find a descriptive subject for your email message, perhaps parts + of the error message. + </para> + + <para> + Do not send bug reports to any of the user mailing lists, such as + pgsql-sql or pgsql-general. These mailing lists are for answering + user questions, 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 + <pgsql-hackers@postgresql.org>. This list is for discussing the + development of <productname>PostgreSQL</productname>, it would be nice + if we could keep the bug reports separate. We might choose take up a + discussion + about your bug report on it, if the bug needs more review. + </para> + + <para> + If you have a problem with the documentation, send email to + <pgsql-docs@postgresql.org>. Refer to the document, chapter, and sections. + </para> + + <para> + If your bug is a portability problem on a non-supported platform, send + mail to <pgsql-ports@postgresql.org>, 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 + email addresses are closed mailing lists. That is, you need to be + subscribed to them in order to be allowed to post. If you simply + want to send mail but do not want to receive list traffic, you can + subscribe to the special pgsql-loophole <quote>list</quote>, which + allows you to post to all <productname>PostgreSQL</productname> + mailing lists without receiving any messages. Send email to + <pgsql-loophole-request@postgresql.org> to subscribe. + </para> + </note> + </Sect2> +</Sect1> -- GitLab