<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/problems.sgml,v 2.13 2002/01/20 22:19:56 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/problems.sgml,v 2.14 2003/04/13 09:56:00 petere Exp $
-->
<sect1 id="bug-reporting">
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 the program does something different from what the
+ 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>
- 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 select statement without the
- preceding create table and insert 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.
- 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> start-up file.) An easy start at 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.
+ 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
+ start at 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</>, then
+ If your application uses some other client interface, such as <application>PHP</>, 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>mid-size databases</quote>, etc. since this
+ 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>
<literal>postmaster --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. You can also look into the
- <filename>README</filename> file
- in the source directory or at the
- name of your distribution file or package name.
+ more than old enough to warrant an upgrade.
If you run a prepackaged 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.
just say <quote>PostgreSQL crashes</quote>. A crash of a single
backend server process is quite different from crash of the parent
<quote>postmaster</> process; please don't say <quote>the postmaster
- crashed</> when you mean a single backend went down, nor vice versa.
+ crashed</> 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.
<email>pgsql-sql@postgresql.org</email> or
<email>pgsql-general@postgresql.org</email>.
These mailing lists are for answering
- user questions and their subscribers normally do not wish to receive
+ user questions, and their subscribers normally do not wish to receive
bug reports. More importantly, they are unlikely to fix them.
</para>
Also, please do <emphasis>not</emphasis> send reports to
the developers' mailing list <email>pgsql-hackers@postgresql.org</email>.
This list is for discussing the
- development of <productname>PostgreSQL</productname> and it would be nice
+ 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.
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 a list to be allowed to post on it. (You need not be
- subscribed to use the bug report web-form, however.)
+ subscribed to use the bug-report web form, however.)
If you would like to send mail but do not want to receive list traffic,
you can subscribe and set your subscription option to <literal>nomail</>.
For more information send mail to
projects / postgresql / commitdiff