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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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