Правила сообщения об ошибках

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

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

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

Выявление ошибок

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

Далее приведены лишь некоторые примеры возможных ошибок:

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

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

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

Что сообщить

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

В каждом отчете об ошибке следует указать следующую информацию:

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

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

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

Примечание
В случае фатальных ошибок сообщение об ошибке на стороне клиента может не содержать всю доступную информацию. Пожалуйста, также просмотрите вывод журнала сервера баз данных. Если вы не сохраняете вывод серверного журнала, самое время начать это делать.
Крайне важно описать результат, который вы ожидали получить. Если вы просто напишете «Эта команда выдает мне такой результат» или «Это не то, чего я ожидал», мы можем запустить ваш пример сами, просмотреть вывод и решить, что все в порядке и результат соответствует ожиданиям. Мы вряд ли будем тратить время на расшифровку точного смысла ваших команд. В частности, воздержитесь от заявлений вроде «Это не то, что делает SQL/Oracle». Выяснение корректного согласно стандартам SQL поведения — не слишком увлекательное занятие, а логика работы других реляционных баз данных может быть не полностью документирована или отличаться в нюансах. (Разумеется, если ваша проблема — аварийное завершение программы, можно пропустить этот пункт).
Все параметры командной строки и другие параметры запуска, включая все связанные переменные среды или файлы конфигурации, которые вы изменяли со значений по умолчанию. Пожалуйста, предоставьте точную информацию. Если вы используете предварительно упакованный дистрибутив, который запускает сервер баз данных во время загрузки, вы должны попытаться выяснить, как это происходит.
Все, что вы сделали не так, как написано в инструкции по установке.
Версию QHB. Чтобы узнать версию сервера, к которому вы подключены можете выполнить команду, SELECT version();. Большинство исполняемых программ тоже поддерживает параметр --version; по крайней мере qhb --version и psql --version должно работать. Если функция или параметры не существуют, значит, скорее всего, вашу версию пора обновить. Если вы запускаете предварительно упакованную версию, например RPM, укажите это, включая любую подверсию, которую может иметь пакет. Если речь идет о снимке Git, укажите это, а также хеш коммита.
Если ваша версия старее актуальной, мы почти наверняка предложим вам ее обновить. В каждом новом выпуске содержится много исправлений и улучшений, поэтому вполне возможно, что ошибка, с которой вы столкнулись в более старой версии QHB, уже исправлена. Мы можем предоставить только ограниченную поддержку для систем, использующих старые версии QHB; если вам этого недостаточно — рассмотрите возможность заключения договора о коммерческой поддержке.
Информация о платформе. Включает в себя имя и версию ядра, библиотеку C/RUST, процессор, информацию о памяти и т. д. В большинстве случаев достаточно сообщить поставщика и версию, но не следует предполагать, что все знают, что именно содержит «Debian» или что все работают на x86_64. Если у вас есть проблемы с установкой, то также понадобится информация о наборе инструментов на вашем компьютере (компилятор, make и т.д.).

Не бойтесь, если ваш отчет об ошибке будет довольно объемным. Лучше сообщить обо всем сразу, чем потом уточнять информацию.

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

При написании отчета об ошибке избегайте путаницы в терминологии. Официальное наименование программного пакета — «КВАНТ-ГИБРИД», для краткости в документации, скорее всего, будет использовано название «QHB». Если вы говорите конкретно о серверном процессе, отметьте это, а не просто говорите «Сбои в QHB». Сбой одного серверного процесса сильно отличается от сбоя родительского процесса «qhb»; пожалуйста, не пишите «сбой сервера», когда имеете в виду, что отключился один серверный процесс, и наоборот. Кроме того, клиентские программы, такие как интерактивный интерфейс «psql», полностью отделены от серверной части. Пожалуйста, постарайтесь указать, где проявляется проблема: на стороне клиента или сервера.

Как сообщать об ошибках

Отправляйте отчеты об ошибках по адресу:

qhb.support@quantom.info

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