5. Как правильно сообщить об ошибке
Пред. НаверхПредисловиеНачало След.

5. Как правильно сообщить об ошибке #

5.1. Диагностика ошибок
5.2. Что сообщать
5.3. Куда сообщать

Если вы найдёте ошибку в Postgres Pro, дайте нам знать о ней. Благодаря вашему отчёту об ошибке, Postgres Pro станет ещё более надёжным, ведь даже при самом высоком качестве кода нельзя гарантировать, что каждый блок и каждая функция Postgres Pro будет работать везде и при любых обстоятельствах.

Следующие предложения призваны помочь вам в составлении отчёта об ошибке, который можно будет обработать эффективно. Мы не требуем их неукоснительного выполнения, но всё же лучше следовать им для общего блага.

5.1. Диагностика ошибок #

Прежде чем сообщать об ошибке, пожалуйста, прочитайте и перечитайте документацию и убедитесь, что вообще возможно сделать то, что вы хотите. Если из документации неясно, можно это сделать или нет, пожалуйста, сообщите и об этом (тогда это ошибка в документации). Если выясняется, что программа делает что-то не так, как написано в документации, это тоже ошибка. Вот лишь некоторые примеры возможных ошибок:

  • Программа завершается с аварийным сигналом или сообщением об ошибке операционной системы, указывающей на проблему в программе. (В качестве контрпримера можно привести сообщение «Нет места на диске» — эту проблему вы должны решить сами.)

  • Программа выдаёт неправильный результат для любых вводимых данных.

  • Программа отказывается принимать допустимые (согласно документации) данные.

  • Программа принимает недопустимые данные без сообщения об ошибке или предупреждения. Но помните: то, что вы считаете недопустимым, мы можем считать приемлемым расширением или совместимым с принятой практикой.

  • Не удаётся установить Postgres Pro на поддерживаемой платформе, выполняя соответствующие инструкции.

Здесь под «программой» подразумевается произвольный исполняемый файл, а не исключительно серверный процесс.

Медленная работа или высокая загрузка ресурсов — это не обязательно ошибка. Также может не быть ошибкой какое-то несоответствие стандарту SQL, если только явно не декларируется соответствие в данном аспекте.

5.2. Что сообщать #

Сообщая о проблеме, постарайтесь изложить все факты. В каждом отчёте об ошибке следует указать:

  • Точную последовательность действий для воспроизведения проблемы, начиная с запуска программы. Она должна быть самодостаточной; если вывод зависит от данных в таблицах, то недостаточно сообщить один лишь SELECT, без предшествующих операторов CREATE TABLE и INSERT.

    Лучший формат теста для проблем с SQL — файл, который можно передать программе psql и увидеть проблему. (И убедитесь, что в вашем файле ~/.psqlrc ничего нет.) Самый простой способ получить такой файл — выгрузить объявления таблиц и данные, необходимые для создания полигона, с помощью pg_dump, а затем добавить проблемный запрос. Постарайтесь сократить размер вашего тестового примера, хотя это не абсолютно необходимо. Если ошибка воспроизводится, мы найдём её в любом случае.

    Если ваше приложение использует какой-то другой клиентский интерфейс, например PHP, пожалуйста, попытайтесь свести ошибку к проблемным запросам.

  • Результат, который вы получаете. Если есть сообщение об ошибке, покажите его. Если программа завершается ошибкой операционной системы, сообщите о ней. Или если ничего не происходит, отразите это. Даже если в результате вашего теста происходит сбой программы или что-то очевидное, мы можем не наблюдать этого у себя. Проще всего будет скопировать текст с терминала, если это возможно.

    Примечание

    Если вы упоминаете сообщение об ошибке, пожалуйста, укажите его в наиболее полной форме. Например, в psql, для этого сначала выполните \set VERBOSITY verbose. Если вы цитируете сообщения из журнала событий сервера, присвойте параметру выполнения log_error_verbosity значение verbose, чтобы журнал был наиболее подробным.

    Примечание

    В случае критических ошибок сообщение на стороне клиента может не содержать всю необходимую информацию. Пожалуйста, также изучите журнал сервера баз данных.

  • Очень важно отметить, какой результат вы ожидали получить. Пожалуйста, приводите ожидаемый результат, если это уместно.

  • Все параметры командной строки и другие параметры запуска, включая все связанные переменные окружения или файлы конфигурации, которые вы изменяли.

  • Всё, что вы делали не так, как написано в инструкциях по установке.

  • Версию Postgres Pro. Чтобы выяснить версию сервера, к которому вы подключены, можно выполнить команду SELECT pgpro_version();. Большинство исполняемых программ также поддерживают параметр --version; как минимум должно работать postgres --version и psql --version.

  • Сведения о платформе, включая название и версию ядра, библиотеки C, характеристики процессора, памяти и т. д.

5.3. Куда сообщать #

В общем случае посылать сообщения об ошибках следует по адресу . Мы просим вас написать информативную тему письма, возможно включив в неё часть сообщения об ошибке.

Не отправляйте отчёты об ошибках, специфичных для Postgres Pro, на адрес поддержки PostgreSQL, так как Postgres Pro не поддерживается сообществом PostgreSQL. Однако вы можете сообщать по адресу обо всех ошибках, связанных с PostgreSQL.

Даже если ваша ошибка не связана с особенностями Postgres Pro, не посылайте сообщения в списки рассылки для пользователей, например в или . Эти рассылки предназначены для ответов на вопросы пользователей, и их подписчики обычно не хотят получать сообщения об ошибках, более того, они вряд ли исправят их.

Также, пожалуйста, не отправляйте отчёты об ошибках в список . Этот список предназначен для обсуждения разработки PostgreSQL, и будет лучше, если сообщения об ошибках будут существовать отдельно. Мы перенесём обсуждение вашей ошибки в pgsql-hackers, если связанная с PostgreSQL проблема потребует дополнительного рассмотрения.

Пред. Наверх След.
4. Соглашения Начало Часть I. Введение
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 Postgres Pro we want to hear about it. Your bug reports play an important part in making Postgres Pro more reliable because even the utmost care cannot guarantee that every part of Postgres Pro 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.

  • Postgres Pro fails to 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. 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 #

When reporting a bug, make sure to state all the facts. Each bug report should contain the following items:

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

    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.

  • The output you got. If there is an error message, show 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.

  • The output you expect is very important to state. Please provide the expected output, if applicable.

  • 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 Postgres Pro version. You can run the command SELECT pgpro_version(); 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.

5.3. Where to Report Bugs #

In general, send bug reports to our support email address at . You are requested to use a descriptive subject for your email message, perhaps parts of the error message.

Do not send bug reports specific to Postgres Pro to the PostgreSQL support email address, as Postgres Pro is not supported by the PostgreSQL community. But you can send reports to for any bugs related to PostgreSQL.

Even if your bug is not specific to Postgres Pro, do not send bug reports to any of the user mailing lists, such as or . These mailing lists are for answering user questions, and 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 the developers' mailing list . This list is for discussing the development of PostgreSQL, and it would be nice if the community could keep the bug reports separate. The community might choose to take up a discussion about your bug report on pgsql-hackers, if the PostgreSQL-related problem needs more review.

Prev Up Next
4. Conventions Home Part I. Tutorial