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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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