11<!--
2- $Header: /cvsroot/pgsql/doc/src/sgml/problems.sgml,v 2.9 2001/09/13 15:55:23 petere Exp $
2+ $Header: /cvsroot/pgsql/doc/src/sgml/problems.sgml,v 2.10 2001/11/18 07:14:49 tgl Exp $
33-->
44
55<sect1 id="bug-reporting">
@@ -8,7 +8,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/problems.sgml,v 2.9 2001/09/13 15:55:23 pet
88 <para>
99 When you find a bug in <productname>PostgreSQL</productname> we want to
1010 hear about it. Your bug reports play an important part in making
11- <productname>PostgreSQL</productname> more reliable because even the utmost
11+ <productname>PostgreSQL</productname> more reliable, because even the utmost
1212 care cannot guarantee that every part of PostgreSQL will work on every
1313 platform under every circumstance.
1414 </para>
@@ -66,7 +66,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/problems.sgml,v 2.9 2001/09/13 15:55:23 pet
6666 <listitem>
6767 <para>
6868 A program accepts invalid input without a notice or error message.
69- Keep in mind that your idea of invalid input might be our idea of
69+ But keep in mind that your idea of invalid input might be our idea of
7070 an extension or compatibility with traditional practice.
7171 </para>
7272 </listitem>
@@ -83,9 +83,10 @@ $Header: /cvsroot/pgsql/doc/src/sgml/problems.sgml,v 2.9 2001/09/13 15:55:23 pet
8383 </para>
8484
8585 <para>
86- Being slow or resource-hogging is not necessarily a bug. Read the documentation
87- or ask on one of the mailing lists for help in tuning your applications. Failing
88- to comply to <acronym>SQL</acronym> is not a bug unless compliance for the
86+ Being slow or resource-hogging is not necessarily a bug. Read the
87+ documentation or ask on one of the mailing lists for help in tuning your
88+ applications. Failing to comply to the <acronym>SQL</acronym> standard is
89+ not necessarily a bug either, unless compliance for the
8990 specific feature is explicitly claimed.
9091 </para>
9192
@@ -161,9 +162,9 @@ $Header: /cvsroot/pgsql/doc/src/sgml/problems.sgml,v 2.9 2001/09/13 15:55:23 pet
161162 </para>
162163 <note>
163164 <para>
164- In case of fatal errors, the error messageprovided by the client might
165- not contain all the information available.In that case, also look at the
166- log output of the database server. If you do not keep your server
165+ In case of fatal errors, the error messagereported by the client might
166+ not contain all the information available.Please also look at the
167+ log output of the database server. If you do not keep your server's log
167168 output, this would be a good time to start doing so.
168169 </para>
169170 </note>
@@ -179,7 +180,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/problems.sgml,v 2.9 2001/09/13 15:55:23 pet
179180 Especially refrain from merely saying that <quote>This is not what SQL says/Oracle
180181 does.</quote> Digging out the correct behavior from <acronym>SQL</acronym>
181182 is not a fun undertaking, nor do we all know how all the other relational
182- databases out there behave. (If your problem is a program crash you can
183+ databases out there behave. (If your problem is a program crash, you can
183184 obviously omit this item.)
184185 </para>
185186 </listitem>
@@ -208,8 +209,9 @@ $Header: /cvsroot/pgsql/doc/src/sgml/problems.sgml,v 2.9 2001/09/13 15:55:23 pet
208209 programs also support a <option>--version</option> option; at least
209210 <literal>postmaster --version</literal> and <literal>psql --version</literal>
210211 should work.
211- If the function or the options do not exist then your version is probably
212- old enough. You can also look into the <filename>README</filename> file
212+ If the function or the options do not exist then your version is
213+ more than old enough to warrant an upgrade. You can also look into the
214+ <filename>README</filename> file
213215 in the source directory or at the
214216 name of your distribution file or package name.
215217 If you run a prepackaged version, such as RPMs, say so, including any
@@ -254,13 +256,16 @@ $Header: /cvsroot/pgsql/doc/src/sgml/problems.sgml,v 2.9 2001/09/13 15:55:23 pet
254256
255257 <para>
256258 When writing a bug report, please choose non-confusing terminology.
257- The software package as such is called <quote>PostgreSQL</quote>,
258- sometimes <quote>Postgres</quote> for short. (Sometimes
259- the abbreviation <quote>Pgsql</quote> is used but don't do that.) When you
259+ The software package in total is called <quote>PostgreSQL</quote>,
260+ sometimes <quote>Postgres</quote> for short. If you
260261 are specifically talking about the backend server, mention that, do not
261- just say <quote>Postgres crashes</quote>. The interactive frontend is called
262- <quote>psql</quote> and is for all intends and purposes completely separate
263- from the backend.
262+ just say <quote>Postgres crashes</quote>. A crash of a single
263+ backend server process is quite different from crash of the parent
264+ <quote>postmaster</> process; please don't say <quote>the postmaster
265+ crashed</> when you mean a single backend went down, nor vice versa.
266+ Also, client programs such as the interactive frontend <quote>psql</quote>
267+ are completely separate from the backend. Please try to be specific
268+ about whether the problem is on the client or server side.
264269 </para>
265270 </sect2>
266271
@@ -270,10 +275,18 @@ $Header: /cvsroot/pgsql/doc/src/sgml/problems.sgml,v 2.9 2001/09/13 15:55:23 pet
270275 <para>
271276 In general, send bug reports to the bug report mailing list at
272277 <email>pgsql-bugs@postgresql.org</email>.
273- You areinvited tofind a descriptive subject for your email
278+ You arerequested touse a descriptive subject for your email
274279 message, perhaps parts of the error message.
275280 </para>
276281
282+ <para>
283+ Another method is to fill in the bug report web-form available
284+ at the project's web site
285+ <ulink url="http://www.postgresql.org/">http://www.postgresql.org/</ulink>.
286+ Entering a bug report this way causes it to be mailed to the
287+ <email>pgsql-bugs@postgresql.org</email> mailing list.
288+ </para>
289+
277290 <para>
278291 Do not send bug reports to any of the user mailing lists, such as
279292 <email>pgsql-sql@postgresql.org</email> or
@@ -290,13 +303,14 @@ $Header: /cvsroot/pgsql/doc/src/sgml/problems.sgml,v 2.9 2001/09/13 15:55:23 pet
290303 development of <productname>PostgreSQL</productname> and it would be nice
291304 if we could keep the bug reports separate. We might choose to take up a
292305 discussion
293- about your bug report onit , if thebug needs more review.
306+ about your bug report onpgsql-hackers , if theproblem needs more review.
294307 </para>
295308
296309 <para>
297- If you have a problem with the documentation, send email to
298- the documentation mailing list <email>pgsql-docs@postgresql.org</email>.
299- Mention the document, chapter, and sections in your problem report.
310+ If you have a problem with the documentation, the best place to report it
311+ is the documentation mailing list <email>pgsql-docs@postgresql.org</email>.
312+ Please be specific about what part of the documentation you are unhappy
313+ with.
300314 </para>
301315
302316 <para>
@@ -310,9 +324,10 @@ $Header: /cvsroot/pgsql/doc/src/sgml/problems.sgml,v 2.9 2001/09/13 15:55:23 pet
310324 <para>
311325 Due to the unfortunate amount of spam going around, all of the above
312326 email addresses are closed mailing lists. That is, you need to be
313- subscribed to a list to be allowed to post on it. If you simply
314- want to send mail but do not want to receive list traffic, you can
315- subscribe and set your subscription option to <literal>nomail</>.
327+ subscribed to a list to be allowed to post on it. (You need not be
328+ subscribed to use the bug report web-form, however.)
329+ If you would like to send mail but do not want to receive list traffic,
330+ you can subscribe and set your subscription option to <literal>nomail</>.
316331 For more information send mail to
317332 <email>majordomo@postgresql.org</email>
318333 with the single word <literal>help</> in the body of the message.