pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedBug reporting guidelines
3+ messages / 3 participants
[nested] [flat]
* Bug reporting guidelines
@ 2000-03-06 15:59 Peter Eisentraut <peter_e@gmx.net>
2000-03-06 23:24 ` Re: [DOCS] Bug reporting guidelines Thomas Lockhart <lockhart@alumni.caltech.edu>
2000-03-07 23:59 ` Re: [DOCS] Bug reporting guidelines Bruce Momjian <pgman@candle.pha.pa.us>
0 siblings, 2 replies; 3+ messages in thread
From: Peter Eisentraut @ 2000-03-06 15:59 UTC (permalink / raw)
To: pgsql-docs
Is everyone okay with the attached bug reporting guidelines? Any
corrections and suggestions whatsoever are welcome.
I've tried to find a careful balance between 'use your common sense' and
'better safe than sorry', albeit skewed to the latter.
(I do have this in DocBook. Just showing it first.)
Thomas, when is the deadline for doc changes? I have some minor
corrections to the installation procedure lying around as well.
--
Peter Eisentraut Sernanders väg 10:115
peter_e@gmx.net 75262 Uppsala
http://yi.org/peter-e/ Sweden
Attachments:
pgsql-bugs.txt (text/plain, 10.1K) download
Bug Reporting Guidelines
When you encounter a bug in PostgreSQL we want to hear about it. Your bug
reports are an important part in making PostgreSQL more reliable because
even the utmost care cannot guarantee that every part of PostgreSQL will
work on every platform under every circumstance.
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.
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.
Identifying Bugs
Before you ask "Is this 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'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:
* A program terminates with a fatal signal or an operating system error
message that would point to a problem in the program (for example not
"disk full").
* A program produces the wrong output for any given input.
* A program refuses to accept valid input.
* A program accepts invalid input without a notice or error message.
* PostgreSQL fails to compile, build, or install according to the
instructions on supported platforms.
Here "program" refers to any executable, not only the backend server.
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 SQL is not a bug unless compliance for
the specific feature is explicitly claimed.
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.
What to report
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 "it
seemed to do", 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 "ring a bell" anyway.
The following items should be contained in every bug report:
* The exact sequence of steps from program startup 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 psql frontend that shows the
problem. (Be sure to not have anything in your ~/.psqlrc 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.
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 "large
files" or "mid-size databases", etc.
* The output you got. Please do not say that it "didn't work" or
"failed". 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.
Note: 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.
* The output you expected is very important to state. If you just write
"This command gives me that output." or "This is not what I expected.",
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 "This is not what SQL says/Oracle does."
Digging out the correct behavior from SQL 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.)
* 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.
* Anything you did at all differently from the installation instructions.
* The PostgreSQL version. You can run the command SELECT version(); 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.
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.
* 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 "Debian" contains or that everyone runs on Pentiums. If you
have installation problems information about compilers, make, etc. is
also necessary.
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.
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.
When writing a bug report, please choose non-confusing terminology. The
software package as such is called "PostgreSQL", sometimes "Postgres" for
short. (Sometimes the abbreviation "Pgsql" is used but don't do that.) When
you are specifically talking about the backend server, mention that, don't
just say "Postgres crashes". The interactive frontend is called "psql" and
is for all intends and purposes completely separate from the backend.
Where to report bugs
In general, send bug reports to <pgsql-bugs@postgresql.org>. You are invited
to find a descriptive subject for your email message, perhaps parts of the
error message.
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.
Also, please do not send reports to <pgsql-hackers@postgresql.org>. This
list is for discussing the development of PostgreSQL, 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.
If you have a problem with the documentation, send email to
<pgsql-docs@postgresql.org>. Refer to the document, chapter, and sections.
If your bug is a portability problem on a non-supported platform, send mail
to <pgsql-ports@postgresql.org>, so we (and you) can work on porting
PostgreSQL to your platform.
Note: 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 "list",
which allows you to post to all PostgreSQL mailing lists without
receiving any messages. Send email to
<pgsql-loophole-request@postgresql.org> to subscribe.
* Re: [DOCS] Bug reporting guidelines
2000-03-06 15:59 Bug reporting guidelines Peter Eisentraut <peter_e@gmx.net>
@ 2000-03-06 23:24 ` Thomas Lockhart <lockhart@alumni.caltech.edu>
1 sibling, 0 replies; 3+ messages in thread
From: Thomas Lockhart @ 2000-03-06 23:24 UTC (permalink / raw)
To: Peter Eisentraut <peter_e@gmx.net>; +Cc: pgsql-docs
> Is everyone okay with the attached bug reporting guidelines? Any
> corrections and suggestions whatsoever are welcome.
> (I do have this in DocBook. Just showing it first.)
Didn't read every line carefully, but it looks very good.
> Thomas, when is the deadline for doc changes? I have some minor
> corrections to the installation procedure lying around as well.
We will try firming up the docs in a couple of weeks, freezing them
soon after. I'll be discussing this on the hackers list, so hopefully
it won't come as a suprise.
- Thomas
--
Thomas Lockhart lockhart@alumni.caltech.edu
South Pasadena, California
^ permalink raw reply [nested|flat] 3+ messages in thread
* Re: [DOCS] Bug reporting guidelines
2000-03-06 15:59 Bug reporting guidelines Peter Eisentraut <peter_e@gmx.net>
@ 2000-03-07 23:59 ` Bruce Momjian <pgman@candle.pha.pa.us>
1 sibling, 0 replies; 3+ messages in thread
From: Bruce Momjian @ 2000-03-07 23:59 UTC (permalink / raw)
To: Peter Eisentraut <peter_e@gmx.net>; +Cc: pgsql-docs
Sounds good.
[Charset ISO-8859-1 unsupported, filtering to ASCII...]
> Is everyone okay with the attached bug reporting guidelines? Any
> corrections and suggestions whatsoever are welcome.
>
> I've tried to find a careful balance between 'use your common sense' and
> 'better safe than sorry', albeit skewed to the latter.
>
> (I do have this in DocBook. Just showing it first.)
>
> Thomas, when is the deadline for doc changes? I have some minor
> corrections to the installation procedure lying around as well.
>
> --
> Peter Eisentraut Sernanders v_g 10:115
> peter_e@gmx.net 75262 Uppsala
> http://yi.org/peter-e/ Sweden
Content-Description: Bug reporting guidelines
[Attachment, skipping...]
--
Bruce Momjian | http://www.op.net/~candle
pgman@candle.pha.pa.us | (610) 853-3000
+ If your life is a hard drive, | 830 Blythe Avenue
+ Christ can be your backup. | Drexel Hill, Pennsylvania 19026
^ permalink raw reply [nested|flat] 3+ messages in thread
end of thread, other threads:[~2000-03-07 23:59 UTC | newest]
Thread overview: 3+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2000-03-06 15:59 Bug reporting guidelines Peter Eisentraut <peter_e@gmx.net>
2000-03-06 23:24 ` Thomas Lockhart <lockhart@alumni.caltech.edu>
2000-03-07 23:59 ` Bruce Momjian <pgman@candle.pha.pa.us>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox