From 2cc8e6ac1fdac25181aca764afa813712c4c7e4e Mon Sep 17 00:00:00 2001 From: "Thomas G. Lockhart" Date: Thu, 30 Mar 2000 22:19:47 +0000 Subject: [PATCH] Renamed from bug-reports.sgml. Not all problems are bugs ;) --- doc/src/sgml/problems.sgml | 314 +++++++++++++++++++++++++++++++++++++ 1 file changed, 314 insertions(+) create mode 100644 doc/src/sgml/problems.sgml diff --git a/doc/src/sgml/problems.sgml b/doc/src/sgml/problems.sgml new file mode 100644 index 0000000000..a82d36eb27 --- /dev/null +++ b/doc/src/sgml/problems.sgml @@ -0,0 +1,314 @@ + + Problem Reporting Guidelines + + + When you encounter a problem in PostgreSQL we want to + hear about it. Your bug reports are an important part in making + PostgreSQL more reliable because even the utmost + care cannot guarantee that every part of PostgreSQL will work on every + platform under every circumstance. + + + + 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. + + + + 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. + + + + Identifying Bugs + + + Before you ask Is this 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'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: + + + + + 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 disk full message, + since that must be fixed outside of Postgres). + + + + + + A program produces the wrong output for any given input. + + + + + + A program refuses to accept valid input. + + + + + + A program accepts invalid input without a notice or error message. + + + + + + PostgreSQL fails to compile, build, or + install according to the instructions on supported platforms. + + + + + Here program refers to any executable, not only the backend server. + + + + 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 SQL is not a bug unless compliance for the + specific feature is explicitly claimed. + + + + 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. + + + + + What to report + + + 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 + it seemed to do, 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 ring a bell + anyway. + + + + The following items should be contained in every bug report: + + + + + The exact sequence of steps from program startup + 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 + psql frontend + that shows the problem. (Be sure to not have anything in your + ~/.psqlrc 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. + + + 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 + large files or mid-size databases, etc. + + + + + + The output you got. Please do not say that it didn't work or + failed. 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. + + + + 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. + + + + + + + The output you expected is very important to state. If you just write + This command gives me that output. or This is not + what I expected., 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 This is not what SQL says/Oracle + does. Digging out the correct behavior from SQL + 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.) + + + + + + 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. + + + + + + Anything you did at all differently from the installation instructions. + + + + + + The PostgreSQL version. You can run the command + SELECT version(); 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. + + + 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. + + + + + + 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 + Debian contains or that everyone runs on Pentiums. If + you have installation problems information about compilers, make, etc. + is also necessary. + + + + + 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. + + + + 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. + + + + When writing a bug report, please choose non-confusing terminology. + The software package as such is called PostgreSQL, + sometimes Postgres for short. (Sometimes + the abbreviation Pgsql is used but don't do that.) When you + are specifically talking about the backend server, mention that, don't + just say Postgres crashes. The interactive frontend is called + psql and is for all intends and purposes completely separate + from the backend. + + + + + Where to report bugs + + + 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. + + + + 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. + + + + Also, please do not send reports to + <pgsql-hackers@postgresql.org>. This list is for discussing the + development of PostgreSQL, 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. + + + + If you have a problem with the documentation, send email to + <pgsql-docs@postgresql.org>. Refer to the document, chapter, and sections. + + + + 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 PostgreSQL to your platform. + + + + + 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 list, which + allows you to post to all PostgreSQL + mailing lists without receiving any messages. Send email to + <pgsql-loophole-request@postgresql.org> to subscribe. + + + + + +