6. Руководство по отправке сообщений об ошибках

6.1. Идентификация ошибок

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

• Программа завершается с фатальным сигналом или сообщением об ошибке операционной системы, которая указывает на проблему в программе. (В качестве примера, с сообщением "disk full" (диск полон), в случае которого вы можете и сами решить проблему.)

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

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

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

• PostgreSQL не компилируется, не собирается или не устанавливается в соответствии с инструкциями на поддерживаемых платформах.

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

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

Перед тем как продолжить, проверьте список TODO и FAQ, чтобы увидеть, известна ли уже обнаруженная вами ошибка. Если вы не можете понять информацию из списка TODO, сообщите о проблеме. Это, по крайней мере, позволит нам сделать список TODO лучше.

6.2. Что нужно сообщить

Наиболее важная вещь - помнить, что сообщение об ошибке должно описывать все факты и только факты. Не нужно расписывать ваши мысли по поводу того, почему вы думаете то или это не работает, или неправильно, что "это видимо надо делать так", или почему та, или иная часть программы ошибочна. Если вы в мельчайших подробностях не разбираетесь в реализации продукта, то вы можете быть неправы и нисколько не поможете нам. И даже если вы очень хорошо разбираетесь, то ваши разъяснения хотя и являются большим дополнением, но все-таки не заменят факты. Если вы хотите исправить эту ошибку, то мы сперва сами должны просто увидеть, что она происходит. Сообщение голых фактов является относительно правильным (вы можете например скопировать и вставить сообщения с экрана), но часто все очень важные детали оказываются опущенными, потому что кто-то посчитает их не имеющими значения. Кроме того сообщение об ошибке может быть понято как-то иначе.

В каждом сообщении об ошибке должны содержаться следующие элементы:

• Точная последовательность шагов от запуска программы, необходимая для воспроизведения проблемы. Эта последовательность должна быть самодостаточной; недостаточно отправить, например, только ваш оператор select без предшествующих ему операторов создания таблицы create table и insert, если вывод должен зависеть от данных в этой таблице. У нас нет времени заниматься обратным реинженирингом схемы вашей базы данных, а если мы попытаемся воспроизвести проблему на наших собственных данных, то мы можем эту проблему и не увидеть. Наилучший формат для тестирования проблемы, относящейся к языку запросов - это файл, который может быть запущен с помощью psql и который показывает эту проблему. (Убедитесь, что в вашем файле ~/.psqlrc ничего нет.) Самый простой способ получения этого файла - это использование pg_dump для создания дампа описания таблицы и данных, нужных для этой таблицы, а затем добавление запроса, в котором возникает проблема. Вы должны минимизировать размер вашего примера, но это не является непременным условием. Если ошибка воспроизводится, мы будем искать её именно этим способом.

  Если ваше приложение использует какие-либо другие клиентские интерфейсы, такие как PHP, попытайтесь изолировать проблему в рамках запросов, поскольку мы скорее всего не будем устанавливать web сервер, чтобы воспроизвести вашу проблему. В любом случае не забывайте предоставить точные входные файлы, не гадайте о том, что ваша проблема случается на "больших файлах" или "базах данных среднего размера" и т.д., так как эта информация слишком неточна для того чтобы её использовать.

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

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

• Выходные данные, которые вы ожидаете - это очень важно. Если вы пишите только, что "Данная команда выдает мне эти данные" или "Это не то, что я ожидал", то мы можем запустить все согласно вашим инструкциям, посмотреть выходные данные и думать, что все в порядке и что все именно так, как мы ожидали. Мы не должны тратить время, чтобы понять точный смысл поведения ваших команд. Особенно воздержитесь от простых фраз типа "Это не то, что делает SQL в Oracle." Выход из рамок корректного поведения SQL - это не шуточное дело, не думайте, что мы всё знаем о том как ведут себя в таких случаях другие реляционные базы данных. (Если вашей проблемой является крах программы, вы можете спокойно пропустить этот абзац).

• Любые опции командной строки и другие опции запуска сервера, включая переменные окружения или файлы с настройками, в которых вы изменили значения по умолчанию. Снова, будьте точны. Если вы используете какой либо пакет из дистрибутива, который производит запуск сервера при загрузке операционной системы, вы должны попытаться найти как он это делает.

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

• Версию PostgreSQL. Вы можете запустить команду SELECT version(); чтобы определить версию сервера, к которому осуществлено подключение. Большинство исполняемых программ также поддерживают опцию --version; по крайней мере postmaster --version и psql --version должно работать. Если указанная функция или опции не существуют, то ваша версия СУБД более чем стара и нуждается в обновлении. Вы также можете посмотреть версию в файле README в каталоге с исходными текстами, а также понять номер версии из файла с дистрибутивом или имени пакета. Если вы запускаете СУБД из пакета, такого как RPM, то также, не забудьте включить любые номера подверсии данного пакета. Если вы ведете речь о CVS версии, напишите источник CVS, включая его дату и время.

  Если ваша версия старше, чем 7.3.3 мы почти наверняка предложим вам сделать обновление. Существует множество исправленных ошибок в каждом новом выпуске, по причине чего, мы, в том числе, и делаем новые выпуски.

• Информация о платформе. Сюда включается имя ядра и его версия, версия C библиотеки, процессор, информация о памяти. В большинстве случаев, вполне достаточно указать производителя дистрибутива и версию, но не думайте, что все знают о том, что такое "Debian" или что каждый работает на процессоре Pentium. Если у вас есть проблемы при установке, то необходима также информация про компиляторы, make и т.д.

Не пугайтесь если ваше сообщение об ошибке будет довольно длинным. Это проза жизни. Гораздо лучше указать всю необходимую информацию сразу, чем нам потом выспрашивать факты у вас. С другой стороны, если ваши выходные файлы огромны, то сперва честно спросите себя: а будет ли кому-либо интересно что-либо в них искать.

Не тратьте всё своё время на описание того, какие изменения во входных данных приводят к устранению проблемы. Такое описание скорее всего не поможет её решить. 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 cannot 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 will find that out soon enough.

Когда описываете ошибку, пожалуйста используйте нормальную терминологию. Программное обеспечение целиком называется "PostgreSQL", иногда для краткости "Postgres". Если вы говорите отдельно про программу-сервер, то не говорите, что "PostgreSQL падает". Нужно также отличать крах backend-сервера, созданного основным postmaster-сервером от краха самого postmaster-сервера; пожалуйста не говорите, что "postmaster упал", когда имеете в виду backend-сервер и наоборот. Также, клиентские программы, такие как интерактивный frontend "psql" должны полностью отделяться от backend-сервера. Пожалуйста попытайтесь уточнить где же именно происходит проблема на стороне клиента или сервера.

6.3. Куда отправлять сообщения об ошибках

Обычно, сообщения об ошибках отправляют в список рассылки об ошибках <[email protected]>. Вы должны использовать тему вашего письма с ярким описанием, например часть сообщения об ошибке.

Другой способ отправки - заполнить web-форму отчета об ошибке, которая доступна на сайте проекта http://www.postgresql.org/. Ввод этой формы приведет к отправке вашего сообщения об ошибке в список рассылки <[email protected]>.

Не отправляйте сообщения об ошибках в какие-либо пользовательские списки рассылки, такие как <[email protected]> или <[email protected]>. Эти списки рассылки предназначены для ответов на вопросы пользователей и их подписчики не хотели бы получть сообщения об ошибках. Что является более важным, они не смогут исправить эти ошибки.

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

Если у вас проблема с документацией, то лучшим местом, где о ней можно сообщить является список рассылки по документации <[email protected]>. Пожалуйста, указывайте точно в какая части документации есть проблемы или ошибки.

Если ваша ошибка связана с проблемой переносимости на неподдерживамую платформу, отправляйте сообщение на <[email protected]>, для того, чтобы мы (и вы) могли работать над переносом PostgreSQL на вашу платформу.