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

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

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

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

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

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

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

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

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

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

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

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

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

  Точно опишите эти изменения — приведите контекстный diff.

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

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

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

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

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

Вот что указывать не обязательно:

• Описание границ проявления ошибки.

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

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

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