5. Bug Reporting Guidelines#

5. Bug Reporting Guidelines
5. Bug Reporting Guidelines
Prev UpPrefaceHome Next

5. Bug Reporting Guidelines

5.1. Identifying Bugs
5.2. What to Report
5.3. Where to Report Bugs

When you find a bug in Tantor SE-1C we want to hear about it. Your bug reports play an important part in making Tantor SE-1C more reliable because even the utmost care cannot guarantee that every part of Tantor SE-1C 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 doing so tends to be to everyone's advantage.

5.1. Identifying Bugs

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:

  • 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 “disk full” message, since you have to fix that yourself.)

  • A program produces the wrong output for any given input.

  • A program refuses to accept valid input (as defined in the documentation).

  • 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.

  • Tantor SE-1C fails to compile, build, or install according to the instructions on supported platforms.

Here “program” refers to any executable, not only the backend process.

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 SQL standard is not necessarily a bug either, unless compliance for the specific feature is explicitly claimed.

5.2. What to Report

The most important thing to remember about bug reporting is to state all the facts and only the facts.

The following items should be contained in every bug report:

  • The exact sequence of steps from program start-up necessary to reproduce the problem. This should be self-contained; it is not enough to send in a bare SELECT statement without the preceding CREATE TABLE and INSERT 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.

    The best format for a test case for SQL-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 start-up file.) An easy way to create this file is to use pg_dump 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.

    If your application uses some other client interface, such as PHP, 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 “large files” or “midsize databases”, etc. since this information is too inexact to be of use.

  • The output you got. Please do not say that it “didn't work” or “crashed”. 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.

    Note

    If you are reporting an error message, please obtain the most verbose form of the message. In psql, say \set VERBOSITY verbose beforehand. If you are extracting the message from the server log, set the run-time parameter log_error_verbosity to verbose so that all details are logged.

    Note

    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.

  • The output you expect is very important to the state.

  • Any command line options and other start-up options, including any relevant environment variables or configuration files that you changed from the default.

  • Anything you did at all differently from the installation instructions.

  • The Tantor SE-1C version. You can run the command SELECT tantor_version(); and SELECT tantor_build(); to find out the version of the server you are connected to. Most executable programs also support a --version option; at least postgres --version and psql --version should work.

  • Platform information. This includes the kernel name and version, C library, processor, memory information, and so on.

Do not be afraid if your bug report becomes rather lengthy. It is better to report everything the first time.

5.3. Where to Report Bugs

You can send bug reports to the following channels:

Support team email:

Customers Support System: lk-new.astralinux.ru

Your account manager (for Enterprise Customers)

Prev Up Next
4. Conventions Home Part I. Tutorial