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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Обычно, сообщения об ошибках отправляют в список рассылки об ошибках <pgsql-bugs@postgresql.org>. Вы должны использовать тему вашего письма с ярким описанием, например часть сообщения об ошибке.

Другой способ отправки - заполнить web-форму отчета об ошибке, которая доступна на веб сайте проекта. Ввод этой формы приведет к отправке вашего сообщения об ошибке в список рассылки <pgsql-bugs@postgresql.org>.

Если ваше сообщение об ошибке содержит какие-либо сведения, которые связаны с секретностью и вы не хотите их появления в открытых архивах, не отправляйте их на pgsql-bugs. Секретные сведения могут быть направлены приватно на адрес <security@postgresql.org>.

Не отправляйте сообщения об ошибках в какие-либо пользовательские списки рассылки, такие как <pgsql-sql@postgresql.org> или <pgsql-general@postgresql.org>. Эти списки рассылки предназначены для ответов на вопросы пользователей и их подписчики не хотели бы получть сообщения об ошибках. Что является более важным, они не смогут исправить эти ошибки.

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

Если у вас проблема с документацией, то лучшим местом, где о ней можно сообщить является список рассылки по документации <pgsql-docs@postgresql.org>. Пожалуйста, указывайте точно в какая части документации есть проблемы или ошибки.

Если ваша ошибка связана с проблемой переносимости на неподдерживамую платформу, отправляйте сообщение на <pgsql-hackers@postgresql.org>, для того, чтобы мы (и вы) могли работать над переносом PostgreSQL на вашу платформу.