← Back to branch summary

~ubuntu-branches/ubuntu/hardy/postgresql-8.4/hardy-backports

« back to all changes in this revision

Viewing changes to doc/src/sgml/problems.sgml

  • Committer: Bazaar Package Importer
  • Author(s): Martin Pitt
  • Date: 2009-03-20 12:00:13 UTC
  • Revision ID: james.westby@ubuntu.com-20090320120013-hogj7egc5mjncc5g
Tags: upstream-8.4~0cvs20090328
Import upstream version 8.4~0cvs20090328

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/sgml/problems.sgml
 
1
<!-- $PostgreSQL$ -->
 
2
 
 
3
<sect1 id="bug-reporting">
 
4
 <title>Bug Reporting Guidelines</title>
 
5
 
 
6
 <para>
 
7
  When you find a bug in <productname>PostgreSQL</productname> we want to
 
8
  hear about it. Your bug reports play an important part in making
 
9
  <productname>PostgreSQL</productname> more reliable because even the utmost
 
10
  care cannot guarantee that every part of
 
11
  <productname>PostgreSQL</productname> 
 
12
  will work on every platform under every circumstance.
 
13
 </para>
 
14
 
 
15
 <para>
 
16
  The following suggestions are intended to assist you in forming bug reports
 
17
  that can be handled in an effective fashion. No one is required to follow
 
18
  them but doing so tends to be to everyone's advantage.
 
19
 </para>
 
20
 
 
21
 <para>
 
22
  We cannot promise to fix every bug right away. If the bug is obvious, critical,
 
23
  or affects a lot of users, chances are good that someone will look into it. It
 
24
  could also happen that we tell you to update to a newer version to see if the
 
25
  bug happens there. Or we might decide that the bug
 
26
  cannot be fixed before some major rewrite we might be planning is done. Or
 
27
  perhaps it is simply too hard and there are more important things on the agenda.
 
28
  If you need help immediately, consider obtaining a commercial support contract.
 
29
 </para>
 
30
 
 
31
 <sect2>
 
32
  <title>Identifying Bugs</title>
 
33
 
 
34
  <para>
 
35
   Before you report a bug, please read and re-read the
 
36
   documentation to verify that you can really do whatever it is you are
 
37
   trying. If it is not clear from the documentation whether you can do
 
38
   something or not, please report that too; it is a bug in the documentation.
 
39
   If it turns out that a program does something different from what the
 
40
   documentation says, that is a bug. That might include, but is not limited to,
 
41
   the following circumstances:
 
42
 
 
43
   <itemizedlist>
 
44
    <listitem>
 
45
     <para>
 
46
      A program terminates with a fatal signal or an operating system
 
47
      error message that would point to a problem in the program. (A
 
48
      counterexample might be a <quote>disk full</quote> message,
 
49
      since you have to fix that yourself.)
 
50
     </para>
 
51
    </listitem>
 
52
 
 
53
    <listitem>
 
54
     <para>
 
55
      A program produces the wrong output for any given input.
 
56
     </para>
 
57
    </listitem>
 
58
 
 
59
    <listitem>
 
60
     <para>
 
61
      A program refuses to accept valid input (as defined in the documentation).
 
62
     </para>
 
63
    </listitem>
 
64
 
 
65
    <listitem>
 
66
     <para>
 
67
      A program accepts invalid input without a notice or error message.
 
68
      But keep in mind that your idea of invalid input might be our idea of
 
69
      an extension or compatibility with traditional practice.
 
70
     </para>
 
71
    </listitem>
 
72
 
 
73
    <listitem>
 
74
     <para>
 
75
      <productname>PostgreSQL</productname> fails to compile, build, or
 
76
      install according to the instructions on supported platforms.
 
77
     </para>
 
78
    </listitem>
 
79
   </itemizedlist>
 
80
 
 
81
   Here <quote>program</quote> refers to any executable, not only the backend server.
 
82
  </para>
 
83
 
 
84
  <para>
 
85
   Being slow or resource-hogging is not necessarily a bug. Read the
 
86
   documentation or ask on one of the mailing lists for help in tuning your
 
87
   applications. Failing to comply to the <acronym>SQL</acronym> standard is
 
88
   not necessarily a bug either, unless compliance for the
 
89
   specific feature is explicitly claimed.
 
90
  </para>
 
91
 
 
92
  <para>
 
93
   Before you continue, check on the TODO list and in the FAQ to see if your bug is
 
94
   already known. If you cannot decode the information on the TODO list, report your
 
95
   problem. The least we can do is make the TODO list clearer.
 
96
  </para>
 
97
 </sect2>
 
98
 
 
99
 <sect2>
 
100
  <title>What to report</title>
 
101
 
 
102
  <para>
 
103
   The most important thing to remember about bug reporting is to state all
 
104
   the facts and only facts. Do not speculate what you think went wrong, what
 
105
   <quote>it seemed to do</quote>, or which part of the program has a fault.
 
106
   If you are not familiar with the implementation you would probably guess
 
107
   wrong and not help us a bit. And even if you are, educated explanations are
 
108
   a great supplement to but no substitute for facts. If we are going to fix
 
109
   the bug we still have to see it happen for ourselves first.
 
110
   Reporting the bare facts
 
111
   is relatively straightforward (you can probably copy and paste them from the
 
112
   screen) but all too often important details are left out because someone
 
113
   thought it does not matter or the report would be understood
 
114
   anyway.
 
115
  </para>
 
116
 
 
117
  <para>
 
118
   The following items should be contained in every bug report:
 
119
 
 
120
   <itemizedlist>
 
121
    <listitem>
 
122
     <para>
 
123
      The exact sequence of steps <emphasis>from program
 
124
      start-up</emphasis> necessary to reproduce the problem. This
 
125
      should be self-contained; it is not enough to send in a bare
 
126
      <command>SELECT</command> statement without the preceding
 
127
      <command>CREATE TABLE</command> and <command>INSERT</command>
 
128
      statements, if the output should depend on the data in the
 
129
      tables. We do not have the time to reverse-engineer your
 
130
      database schema, and if we are supposed to make up our own data
 
131
      we would probably miss the problem.
 
132
     </para>
 
133
 
 
134
     <para>
 
135
      The best format for a test case for SQL-related problems is a
 
136
      file that can be run through the <application>psql</application>
 
137
      frontend that shows the problem. (Be sure to not have anything
 
138
      in your <filename>~/.psqlrc</filename> start-up file.)  An easy
 
139
      start at this file is to use <application>pg_dump</application>
 
140
      to dump out the table declarations and data needed to set the
 
141
      scene, then add the problem query.  You are encouraged to
 
142
      minimize the size of your example, but this is not absolutely
 
143
      necessary.  If the bug is reproducible, we will find it either
 
144
      way.
 
145
     </para>
 
146
 
 
147
     <para>
 
148
      If your application uses some other client interface, such as <application>PHP</>, then
 
149
      please try to isolate the offending queries. We will probably not set up a
 
150
      web server to reproduce your problem. In any case remember to provide
 
151
      the exact input files; do not guess that the problem happens for
 
152
      <quote>large files</quote> or <quote>midsize databases</quote>, etc. since this
 
153
      information is too inexact to be of use.
 
154
     </para>
 
155
    </listitem>
 
156
 
 
157
    <listitem>
 
158
     <para>
 
159
      The output you got. Please do not say that it <quote>didn't work</quote> or
 
160
      <quote>crashed</quote>. If there is an error message,
 
161
      show it, even if you do not understand it. If the program terminates with
 
162
      an operating system error, say which. If nothing at all happens, say so.
 
163
      Even if the result of your test case is a program crash or otherwise obvious
 
164
      it might not happen on our platform. The easiest thing is to copy the output
 
165
      from the terminal, if possible.
 
166
     </para>
 
167
     <note>
 
168
      <para>
 
169
       If you are reporting an error message, please obtain the most verbose
 
170
       form of the message.  In <application>psql</>, say <literal>\set
 
171
       VERBOSITY verbose</> beforehand.  If you are extracting the message
 
172
       from the server log, set the run-time parameter
 
173
       <xref linkend="guc-log-error-verbosity"> to <literal>verbose</> so that all
 
174
       details are logged.
 
175
      </para>
 
176
     </note>
 
177
     <note>
 
178
      <para>
 
179
       In case of fatal errors, the error message reported by the client might
 
180
       not contain all the information available. Please also look at the
 
181
       log output of the database server. If you do not keep your server's log
 
182
       output, this would be a good time to start doing so.
 
183
      </para>
 
184
     </note>
 
185
    </listitem>
 
186
 
 
187
    <listitem>
 
188
     <para>
 
189
      The output you expected is very important to state. If you just write
 
190
      <quote>This command gives me that output.</quote> or <quote>This is not
 
191
      what I expected.</quote>, we might run it ourselves, scan the output, and
 
192
      think it looks OK and is exactly what we expected. We should not have to
 
193
      spend the time to decode the exact semantics behind your commands.
 
194
      Especially refrain from merely saying that <quote>This is not what SQL says/Oracle
 
195
      does.</quote> Digging out the correct behavior from <acronym>SQL</acronym>
 
196
      is not a fun undertaking, nor do we all know how all the other relational
 
197
      databases out there behave. (If your problem is a program crash, you can
 
198
      obviously omit this item.)
 
199
     </para>
 
200
    </listitem>
 
201
 
 
202
    <listitem>
 
203
     <para>
 
204
      Any command line options and other start-up options, including
 
205
      any relevant environment variables or configuration files that
 
206
      you changed from the default. Again, please provide exact
 
207
      information. If you are using a prepackaged distribution that
 
208
      starts the database server at boot time, you should try to find
 
209
      out how that is done.
 
210
     </para>
 
211
    </listitem>
 
212
 
 
213
    <listitem>
 
214
     <para>
 
215
      Anything you did at all differently from the installation
 
216
      instructions.
 
217
     </para>
 
218
    </listitem>
 
219
 
 
220
    <listitem>
 
221
     <para>
 
222
      The <productname>PostgreSQL</productname> version. You can run the command
 
223
      <literal>SELECT version();</literal> to
 
224
      find out the version of the server you are connected to.  Most executable
 
225
      programs also support a <option>--version</option> option; at least
 
226
      <literal>postgres --version</literal> and <literal>psql --version</literal>
 
227
      should work.
 
228
      If the function or the options do not exist then your version is
 
229
      more than old enough to warrant an upgrade.
 
230
      If you run a prepackaged version, such as RPMs, say so, including any
 
231
      subversion the package might have. If you are talking about a CVS
 
232
      snapshot, mention that, including its date and time.
 
233
     </para>
 
234
 
 
235
     <para>
 
236
      If your version is older than &version; we will almost certainly
 
237
      tell you to upgrade. There are many bug fixes and improvements
 
238
      in each new release, so it is quite possible that a bug you have
 
239
      encountered in an older release of <productname>PostgreSQL</>
 
240
      has already been fixed. We can only provide limited support for
 
241
      sites using older releases of <productname>PostgreSQL</>; if you
 
242
      require more than we can provide, consider acquiring a
 
243
      commercial support contract.
 
244
     </para>
 
245
     <para>
 
246
     </para>
 
247
    </listitem>
 
248
 
 
249
    <listitem>
 
250
     <para>
 
251
      Platform information. This includes the kernel name and version,
 
252
      C library, processor, memory information, and so on. In most
 
253
      cases it is sufficient to report the vendor and version, but do
 
254
      not assume everyone knows what exactly <quote>Debian</quote>
 
255
      contains or that everyone runs on Pentiums. If you have
 
256
      installation problems then information about the toolchain on
 
257
      your machine (compiler, <application>make</application>, and so
 
258
      on) is also necessary.
 
259
     </para>
 
260
    </listitem>
 
261
   </itemizedlist>
 
262
 
 
263
   Do not be afraid if your bug report becomes rather lengthy. That is a fact of life.
 
264
   It is better to report everything the first time than us having to squeeze the
 
265
   facts out of you. On the other hand, if your input files are huge, it is
 
266
   fair to ask first whether somebody is interested in looking into it.  Here is
 
267
   an <ulink url="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html">article</ulink>
 
268
   that outlines some more tips on reporting bugs.
 
269
  </para>
 
270
 
 
271
  <para>
 
272
   Do not spend all your time to figure out which changes in the input make
 
273
   the problem go away. This will probably not help solving it. If it turns
 
274
   out that the bug cannot be fixed right away, you will still have time to
 
275
   find and share your work-around. Also, once again, do not waste your time
 
276
   guessing why the bug exists. We will find that out soon enough.
 
277
  </para>
 
278
 
 
279
  <para>
 
280
   When writing a bug report, please avoid confusing terminology.
 
281
   The software package in total is called <quote>PostgreSQL</quote>,
 
282
   sometimes <quote>Postgres</quote> for short. If you
 
283
   are specifically talking about the backend server, mention that, do not
 
284
   just say <quote>PostgreSQL crashes</quote>.  A crash of a single
 
285
   backend server process is quite different from crash of the parent
 
286
   <quote>postgres</> process; please don't say <quote>the server
 
287
   crashed</> when you mean a single backend process went down, nor vice versa.
 
288
   Also, client programs such as the interactive frontend <quote><application>psql</application></quote>
 
289
   are completely separate from the backend.  Please try to be specific
 
290
   about whether the problem is on the client or server side.
 
291
  </para>
 
292
 </sect2>
 
293
 
 
294
 <sect2>
 
295
  <title>Where to report bugs</title>
 
296
 
 
297
  <para>
 
298
   In general, send bug reports to the bug report mailing list at
 
299
   <email>pgsql-bugs@postgresql.org</email>.
 
300
   You are requested to use a descriptive subject for your email
 
301
   message, perhaps parts of the error message.
 
302
  </para>
 
303
 
 
304
  <para> 
 
305
   Another method is to fill in the bug report web-form available
 
306
   at the project's
 
307
   <ulink url="http://www.postgresql.org/">web site</ulink>.
 
308
   Entering a bug report this way causes it to be mailed to the
 
309
   <email>pgsql-bugs@postgresql.org</email> mailing list.
 
310
  </para>
 
311
 
 
312
  <para>
 
313
   If your bug report has security implications and you'd prefer that it
 
314
   not become immediately visible in public archives, don't send it to
 
315
   <literal>pgsql-bugs</literal>.  Security issues can be
 
316
   reported privately to <email>security@postgresql.org</email>.
 
317
  </para>
 
318
 
 
319
  <para> 
 
320
   Do not send bug reports to any of the user mailing lists, such as
 
321
   <email>pgsql-sql@postgresql.org</email> or
 
322
   <email>pgsql-general@postgresql.org</email>.
 
323
   These mailing lists are for answering
 
324
   user questions, and their subscribers normally do not wish to receive
 
325
   bug reports. More importantly, they are unlikely to fix them.
 
326
  </para>
 
327
 
 
328
  <para>
 
329
   Also, please do <emphasis>not</emphasis> send reports to
 
330
   the developers' mailing list <email>pgsql-hackers@postgresql.org</email>.
 
331
   This list is for discussing the
 
332
   development of <productname>PostgreSQL</productname>, and it would be nice
 
333
   if we could keep the bug reports separate. We might choose to take up a
 
334
   discussion about your bug report on <literal>pgsql-hackers</literal>,
 
335
   if the problem needs more review.
 
336
  </para>
 
337
 
 
338
  <para>
 
339
   If you have a problem with the documentation, the best place to report it
 
340
   is the documentation mailing list <email>pgsql-docs@postgresql.org</email>.
 
341
   Please be specific about what part of the documentation you are unhappy
 
342
   with.
 
343
  </para>
 
344
 
 
345
  <para>
 
346
   If your bug is a portability problem on a non-supported platform,
 
347
   send mail to <email>pgsql-hackers@postgresql.org</email>,
 
348
   so we (and you) can work on
 
349
   porting <productname>PostgreSQL</productname> to your platform.
 
350
  </para>
 
351
 
 
352
  <note>
 
353
   <para>
 
354
    Due to the unfortunate amount of spam going around, all of the above
 
355
    email addresses are closed mailing lists. That is, you need to be
 
356
    subscribed to a list to be allowed to post on it.  (You need not be
 
357
    subscribed to use the bug-report web form, however.)
 
358
    If you would like to send mail but do not want to receive list traffic,
 
359
    you can subscribe and set your subscription option to <literal>nomail</>.
 
360
    For more information send mail to
 
361
    <email>majordomo@postgresql.org</email>
 
362
    with the single word <literal>help</> in the body of the message.
 
363
   </para>
 
364
  </note>
 
365
 </sect2>
 
366
</sect1>