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

Отправляйте сообщения об ошибках для Octave на сайт отслеживания ошибок Octave по адресу https://bugs.octave.org.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Вот некоторые вещи, которые не требуются:

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

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

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

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