1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
5
>Bug Reporting Guidelines</TITLE
8
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
10
HREF="mailto:pgsql-docs@postgresql.org"><LINK
12
TITLE="PostgreSQL 9.1beta1 Documentation"
13
HREF="index.html"><LINK
16
HREF="preface.html"><LINK
18
TITLE="Further Information"
19
HREF="resources.html"><LINK
22
HREF="tutorial.html"><LINK
25
HREF="stylesheet.css"><META
26
HTTP-EQUIV="Content-Type"
27
CONTENT="text/html; charset=ISO-8859-1"><META
29
CONTENT="2011-04-27T21:20:33"></HEAD
35
SUMMARY="Header navigation table"
47
>PostgreSQL 9.1beta1 Documentation</A
56
TITLE="Further Information"
105
>Bug Reporting Guidelines</A
108
> When you find a bug in <SPAN
112
hear about it. Your bug reports play an important part in making
116
> more reliable because even the utmost
117
care cannot guarantee that every part of
122
will work on every platform under every circumstance.
125
> The following suggestions are intended to assist you in forming bug reports
126
that can be handled in an effective fashion. No one is required to follow
127
them but doing so tends to be to everyone's advantage.
130
> We cannot promise to fix every bug right away. If the bug is obvious, critical,
131
or affects a lot of users, chances are good that someone will look into it. It
132
could also happen that we tell you to update to a newer version to see if the
133
bug happens there. Or we might decide that the bug
134
cannot be fixed before some major rewrite we might be planning is done. Or
135
perhaps it is simply too hard and there are more important things on the agenda.
136
If you need help immediately, consider obtaining a commercial support contract.
147
> Before you report a bug, please read and re-read the
148
documentation to verify that you can really do whatever it is you are
149
trying. If it is not clear from the documentation whether you can do
150
something or not, please report that too; it is a bug in the documentation.
151
If it turns out that a program does something different from what the
152
documentation says, that is a bug. That might include, but is not limited to,
153
the following circumstances:
160
> A program terminates with a fatal signal or an operating system
161
error message that would point to a problem in the program. (A
162
counterexample might be a <SPAN
166
since you have to fix that yourself.)
171
> A program produces the wrong output for any given input.
176
> A program refuses to accept valid input (as defined in the documentation).
181
> A program accepts invalid input without a notice or error message.
182
But keep in mind that your idea of invalid input might be our idea of
183
an extension or compatibility with traditional practice.
191
> fails to compile, build, or
192
install according to the instructions on supported platforms.
201
> refers to any executable, not only the backend process.
204
> Being slow or resource-hogging is not necessarily a bug. Read the
205
documentation or ask on one of the mailing lists for help in tuning your
206
applications. Failing to comply to the <ACRONYM
210
not necessarily a bug either, unless compliance for the
211
specific feature is explicitly claimed.
214
> Before you continue, check on the TODO list and in the FAQ to see if your bug is
215
already known. If you cannot decode the information on the TODO list, report your
216
problem. The least we can do is make the TODO list clearer.
228
> The most important thing to remember about bug reporting is to state all
229
the facts and only facts. Do not speculate what you think went wrong, what
232
>"it seemed to do"</SPAN
233
>, or which part of the program has a fault.
234
If you are not familiar with the implementation you would probably guess
235
wrong and not help us a bit. And even if you are, educated explanations are
236
a great supplement to but no substitute for facts. If we are going to fix
237
the bug we still have to see it happen for ourselves first.
238
Reporting the bare facts
239
is relatively straightforward (you can probably copy and paste them from the
240
screen) but all too often important details are left out because someone
241
thought it does not matter or the report would be understood
245
> The following items should be contained in every bug report:
252
> The exact sequence of steps <SPAN
259
> necessary to reproduce the problem. This
260
should be self-contained; it is not enough to send in a bare
264
> statement without the preceding
272
statements, if the output should depend on the data in the
273
tables. We do not have the time to reverse-engineer your
274
database schema, and if we are supposed to make up our own data
275
we would probably miss the problem.
278
> The best format for a test case for SQL-related problems is a
279
file that can be run through the <SPAN
283
frontend that shows the problem. (Be sure to not have anything
287
> start-up file.) An easy
288
way to create this file is to use <SPAN
292
to dump out the table declarations and data needed to set the
293
scene, then add the problem query. You are encouraged to
294
minimize the size of your example, but this is not absolutely
295
necessary. If the bug is reproducible, we will find it either
299
> If your application uses some other client interface, such as <SPAN
303
please try to isolate the offending queries. We will probably not set up a
304
web server to reproduce your problem. In any case remember to provide
305
the exact input files; do not guess that the problem happens for
311
>"midsize databases"</SPAN
313
information is too inexact to be of use.
318
> The output you got. Please do not say that it <SPAN
325
>. If there is an error message,
326
show it, even if you do not understand it. If the program terminates with
327
an operating system error, say which. If nothing at all happens, say so.
328
Even if the result of your test case is a program crash or otherwise obvious
329
it might not happen on our platform. The easiest thing is to copy the output
330
from the terminal, if possible.
339
> If you are reporting an error message, please obtain the most verbose
340
form of the message. In <SPAN
346
VERBOSITY verbose</TT
347
> beforehand. If you are extracting the message
348
from the server log, set the run-time parameter
350
HREF="runtime-config-logging.html#GUC-LOG-ERROR-VERBOSITY"
351
>log_error_verbosity</A
367
> In case of fatal errors, the error message reported by the client might
368
not contain all the information available. Please also look at the
369
log output of the database server. If you do not keep your server's log
370
output, this would be a good time to start doing so.
377
> The output you expected is very important to state. If you just write
380
>"This command gives me that output."</SPAN
384
what I expected."</SPAN
385
>, we might run it ourselves, scan the output, and
386
think it looks OK and is exactly what we expected. We should not have to
387
spend the time to decode the exact semantics behind your commands.
388
Especially refrain from merely saying that <SPAN
390
>"This is not what SQL says/Oracle
392
> Digging out the correct behavior from <ACRONYM
396
is not a fun undertaking, nor do we all know how all the other relational
397
databases out there behave. (If your problem is a program crash, you can
398
obviously omit this item.)
403
> Any command line options and other start-up options, including
404
any relevant environment variables or configuration files that
405
you changed from the default. Again, please provide exact
406
information. If you are using a prepackaged distribution that
407
starts the database server at boot time, you should try to find
408
out how that is done.
413
> Anything you did at all differently from the installation
422
> version. You can run the command
425
>SELECT version();</TT
427
find out the version of the server you are connected to. Most executable
428
programs also support a <TT
434
>postgres --version</TT
440
If the function or the options do not exist then your version is
441
more than old enough to warrant an upgrade.
442
If you run a prepackaged version, such as RPMs, say so, including any
443
subversion the package might have. If you are talking about a Git
444
snapshot, mention that, including the commit hash.
447
> If your version is older than 9.1beta1 we will almost certainly
448
tell you to upgrade. There are many bug fixes and improvements
449
in each new release, so it is quite possible that a bug you have
450
encountered in an older release of <SPAN
454
has already been fixed. We can only provide limited support for
455
sites using older releases of <SPAN
459
require more than we can provide, consider acquiring a
460
commercial support contract.
467
> Platform information. This includes the kernel name and version,
468
C library, processor, memory information, and so on. In most
469
cases it is sufficient to report the vendor and version, but do
470
not assume everyone knows what exactly <SPAN
474
contains or that everyone runs on i386s. If you have
475
installation problems then information about the toolchain on
476
your machine (compiler, <SPAN
480
on) is also necessary.
486
Do not be afraid if your bug report becomes rather lengthy. That is a fact of life.
487
It is better to report everything the first time than us having to squeeze the
488
facts out of you. On the other hand, if your input files are huge, it is
489
fair to ask first whether somebody is interested in looking into it. Here is
491
HREF="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html"
495
that outlines some more tips on reporting bugs.
498
> Do not spend all your time to figure out which changes in the input make
499
the problem go away. This will probably not help solving it. If it turns
500
out that the bug cannot be fixed right away, you will still have time to
501
find and share your work-around. Also, once again, do not waste your time
502
guessing why the bug exists. We will find that out soon enough.
505
> When writing a bug report, please avoid confusing terminology.
506
The software package in total is called <SPAN
514
are specifically talking about the backend process, mention that, do not
517
>"PostgreSQL crashes"</SPAN
518
>. A crash of a single
519
backend process is quite different from crash of the parent
523
> process; please don't say <SPAN
527
> when you mean a single backend process went down, nor vice versa.
528
Also, client programs such as the interactive frontend <SPAN
535
are completely separate from the backend. Please try to be specific
536
about whether the problem is on the client or server side.
545
>Where to Report Bugs</A
548
> In general, send bug reports to the bug report mailing list at
552
HREF="mailto:pgsql-bugs@postgresql.org"
553
>pgsql-bugs@postgresql.org</A
556
You are requested to use a descriptive subject for your email
557
message, perhaps parts of the error message.
560
> Another method is to fill in the bug report web-form available
563
HREF="http://www.postgresql.org/"
567
Entering a bug report this way causes it to be mailed to the
571
HREF="mailto:pgsql-bugs@postgresql.org"
572
>pgsql-bugs@postgresql.org</A
577
> If your bug report has security implications and you'd prefer that it
578
not become immediately visible in public archives, don't send it to
582
>. Security issues can be
583
reported privately to <CODE
586
HREF="mailto:security@postgresql.org"
587
>security@postgresql.org</A
592
> Do not send bug reports to any of the user mailing lists, such as
596
HREF="mailto:pgsql-sql@postgresql.org"
597
>pgsql-sql@postgresql.org</A
603
HREF="mailto:pgsql-general@postgresql.org"
604
>pgsql-general@postgresql.org</A
607
These mailing lists are for answering
608
user questions, and their subscribers normally do not wish to receive
609
bug reports. More importantly, they are unlikely to fix them.
612
> Also, please do <SPAN
619
the developers' mailing list <CODE
622
HREF="mailto:pgsql-hackers@postgresql.org"
623
>pgsql-hackers@postgresql.org</A
626
This list is for discussing the
630
>, and it would be nice
631
if we could keep the bug reports separate. We might choose to take up a
632
discussion about your bug report on <TT
636
if the problem needs more review.
639
> If you have a problem with the documentation, the best place to report it
640
is the documentation mailing list <CODE
643
HREF="mailto:pgsql-docs@postgresql.org"
644
>pgsql-docs@postgresql.org</A
647
Please be specific about what part of the documentation you are unhappy
651
> If your bug is a portability problem on a non-supported platform,
655
HREF="mailto:pgsql-hackers@postgresql.org"
656
>pgsql-hackers@postgresql.org</A
659
so we (and you) can work on
672
> Due to the unfortunate amount of spam going around, all of the above
673
email addresses are closed mailing lists. That is, you need to be
674
subscribed to a list to be allowed to post on it. (You need not be
675
subscribed to use the bug-report web form, however.)
676
If you would like to send mail but do not want to receive list traffic,
677
you can subscribe and set your subscription option to <TT
681
For more information send mail to
685
HREF="mailto:majordomo@postgresql.org"
686
>majordomo@postgresql.org</A
689
with the single word <TT
692
> in the body of the message.
703
SUMMARY="Footer navigation table"
714
HREF="resources.html"
742
>Further Information</TD
b'\\ No newline at end of file'