Adding upstream version 14.5.upstream/14.5upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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>