D.2.3 Как сообщать об ошибках ¶

Отправляйте отчеты об ошибках для Octave в трекер ошибок Octave https://bugs.octave.org.

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

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

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

Иногда люди приводят несколько неясных фактов и спрашивают: «Это вам что-нибудь говорит?» Это не поможет нам исправить ошибку. Лучше сразу отправить полный отчет об ошибке.

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

Чтобы помочь кому-то расследовать ошибку, вы должны включить все эти вещи:

• Версия Octave. Вы можете получить ее, обратив внимание на номер версии, который отображается при запуске Octave, или запустив его с опцией «-v».
• Полный входной файл, который воспроизводит ошибку.

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

• Аргументы команд, которые вы передали Octave для выполнения этого примера и наблюдения за ошибкой. Чтобы гарантировать, что вы не пропустите что-то важное, перечислите все параметры.

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

• Тип машины, которую вы используете, а также имя и номер версии операционной системы.
• Аргументы командной строки, которые вы передали команде configure при установке интерпретатора.
• Полный список всех внесенных вами изменений в исходный код интерпретатора.

  Будьте точны в этих изменениях — покажите контекстный diff для них.

• Подробности о любых других отклонениях от стандартной процедуры установки Octave.
• Описание наблюдаемого поведения, которое, по вашему мнению, является неправильным. Например, «Интерпретатор получает фатальный сигнал» или «Выходные данные, полученные на строке 208, некорректны».

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

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

  Часто наблюдаемым симптомом является некорректный вывод при выполнении вашей программы. К сожалению, этого недостаточно для информации, если программа короткая и простая. Очень полезно, если вы можете включить объяснение ожидаемого вывода и почему фактический вывод некорректен.

• Если вы хотите предложить изменения в исходном коде Octave, отправьте их в виде контекстных diff. Если вы даже обсуждаете что-то в исходном коде Octave, ссылайтесь на него по контексту, а не по номеру строки, потому что номера строк в исходных кодах разработки, вероятно, не будут совпадать с номерами строк в ваших исходных кодах.

Вот некоторые вещи, которые не нужны:

• Описание области ошибки.

  Часто люди, которые сталкиваются с ошибкой, тратят много времени на выявление того, какие изменения во входном файле устранят ошибку, а какие изменений не повлияют на нее. Как правило, такая информация не нужна, чтобы исправить ошибки в Octave, но если вы можете найти более простой пример для отчета вместо оригинального, это удобно. Ошибки в выводе будут легче заметить, работа с отладчиком займет меньше времени и т. д. Большинство ошибок Octave связаны только с одной функцией, поэтому наиболее простой способ упростить пример — удалить все определения функций, кроме той, в которой происходит ошибка.

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

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