Renamed from bug-reports.sgml. Not all problems are bugs ;)

diff --git a/doc/src/sgml/problems.sgml b/doc/src/sgml/problems.sgml
new file mode 100644 (file)
index 0000000..a82d36e
--- /dev/null
+++ b/doc/src/sgml/problems.sgml
@@ -0,0 +1,314 @@
+<sect1>
+ <title>Problem Reporting Guidelines</title>
+
+ <para>
+  When you encounter a problem 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 (a
+      counterexample might be a <quote>disk full</quote> message,
+      since that must be fixed outside of <productname>Postgres</productname>).
+     </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 &lt;pgsql-bugs@postgresql.org&gt;. 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
+   &lt;pgsql-hackers@postgresql.org&gt;. 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
+   &lt;pgsql-docs@postgresql.org&gt;. Refer to the document, chapter, and sections.
+  </para>
+ 
+  <para>
+   If your bug is a portability problem on a non-supported platform, send
+   mail to &lt;pgsql-ports@postgresql.org&gt;, 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
+    &lt;pgsql-loophole-request@postgresql.org&gt; to subscribe.
+   </para>
+  </note>
+ </sect2>
+</sect1>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode:sgml
+sgml-omittag:nil
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:"./reference.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:("/usr/lib/sgml/catalog")
+sgml-local-ecat-files:nil
+End:
+-->