perlbug

СОДЕРЖАНИЕ

• ИМЯ
• СИНОПСИС
• ОПИСАНИЕ
• ПАРАМЕТРЫ
• АВТОРЫ
• СМОТРИТЕ ТАКЖЕ
• ОШИБКИ

ИМЯ

perlbug - как отправить отчеты об ошибках в Perl

СИНОПСИС

perlbug

perlbug [ -v ] [ -a адрес ] [ -s тема ] [ -b тело | -f входной_файл ] [ -F выходной_файл ] [ -r адрес_возврата ] [ -e редактор ] [ -c адрес_администратора | -C ] [ -S ] [ -t ] [ -d ] [ -h ] [ -T ]

perlbug [ -v ] [ -r адрес_возврата ] [ -ok | -okay | -nok | -nokay ]

perlthanks

ОПИСАНИЕ

Эта программа предназначена для помощи в составлении отчетов об ошибках (и благодарственных записок) по perl5 и модулям, поставляемым с ним.

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

Если вы обнаружили ошибку с нестандартным портом (который не входил в стандартную дистрибуцию), двоичным дистрибутивом или модулем, не входящим в ядро (таким как Tk, DBI и т. д.), ознакомьтесь с документацией, поставляемой с этим дистрибутивом, чтобы определить правильное место для сообщения об ошибках.

Отчеты об ошибках следует отправлять в систему отслеживания проблем GitHub по адресу https://github.com/Perl/perl5/issues. Адрес perlbug@perl.org больше не открывает автоматически тикеты. Вы можете использовать этот инструмент для составления отчета и сохранения его в файле, который затем можно отправить в систему отслеживания проблем.

В крайних случаях perlbug может не работать достаточно хорошо на вашей системе, чтобы направлять вас в составлении отчета об ошибке. В таких случаях вы можете использовать perlbug -d или perl -V, чтобы получить информацию о конфигурации системы для включения в ваш отчет об ошибке.

При сообщении об ошибке, пожалуйста, пройдите по этому контрольному списку:

Какая версия Perl у вас установлена?

Введите perl -v в командной строке, чтобы узнать.

Используете ли вы последнюю релизную версию perl?

Посмотрите http://www.perl.org/, чтобы узнать. Если вы не используете последнюю релизную версию, попробуйте воспроизвести ошибку на последней стабильной версии.

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

Вы уверены, что имеете дело с ошибкой?

Значительное количество отчетов об ошибках, которые мы получаем, оказываются задокументированными функциями в Perl. Убедитесь, что проблема, с которой вы столкнулись, не является намеренной, взглянув на документацию, поставляемую с дистрибутивом Perl.

Учитывая огромный объем документации Perl, это не тривиальная задача, но если вы можете указать на документацию, которая предполагает, что наблюдаемое поведение является неверным, ваша проблема, скорее всего, получит больше внимания. Вы можете начать с perldoc perltrap, чтобы получить подсказки о распространенных ловушках, с которыми сталкиваются новые (и опытные) программисты Perl.

Если вы не уверены в значении сообщения об ошибке, которое вы получили, посмотрите perldoc perldiag для объяснения. Если сообщение отсутствует в perldiag, оно, вероятно, не генерируется Perl. Возможно, вам удастся обратиться к документации вашей операционной системы.

Если вы работаете на платформе, отличной от UNIX, проконсультируйтесь с perldoc perlport, так как некоторые функции могут быть не реализованы или работать по-другому.

Возможно, вы сможете выяснить, что происходит неправильно, используя отладчик Perl. Для получения информации о том, как использовать отладчик, посмотрите perldoc perldebug.

Есть ли у вас подходящий тестовый случай?

Чем легче воспроизвести вашу ошибку, тем больше вероятность того, что она будет исправлена — если никто не может воспроизвести вашу проблему, то она, вероятно, не будет обработана.

Хороший тестовый случай обладает большинством из этих характеристик: короткий, простой код; мало зависимостей от внешних команд, модулей или библиотек; отсутствие платформозависимого кода (если это не ошибка, специфичная для платформы); понятная, простая документация.

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

Включили ли вы всю необходимую информацию?

Убедитесь, что вы включили точное сообщение об ошибке, если оно есть. «Perl выдал ошибку» — это не точное сообщение об ошибке.

Если у вас сгенерирован дамп ядра (или эквивалент), вы можете использовать отладчик (dbx, gdb и т. д.) для создания стека вызовов, который следует включить в отчет об ошибке.

ПРИМЕЧАНИЕ: если ваш Perl был скомпилирован с отладочной информацией (часто -g), стек вызовов, скорее всего, будет несколько сложным в использовании, так как он, скорее всего, будет содержать только имена функций, а не их аргументы. Если возможно, перекомпилируйте свой Perl с отладочной информацией и воспроизведите сбой и стек вызовов.

Можете ли вы описать ошибку простым языком?

Чем легче понять воспроизводимую ошибку, тем больше вероятность того, что она будет исправлена. Любое понимание проблемы будет очень полезно. Другими словами, постарайтесь проанализировать проблему (в той мере, в которой это возможно) и сообщить о своих выводах.

Можете ли вы исправить ошибку самостоятельно?

Если да, это отличная новость; сообщения об ошибках с исправлениями, скорее всего, получат значительно больше внимания и интереса, чем те, которые без них. Отправьте свое исправление через поток запросов на добавление в GitHub, как описано в perldoc perlhack. Вы также можете отправить исправления на perl5-porters@perl.org. При отправке исправления создайте его с использованием git format-patch если это возможно, хотя унифицированная разница, созданная с использованием diff -pu, будет почти так же хороша.

Ваше исправление может быть возвращено с запросами на внесение изменений или запросами на более подробные объяснения вашего исправления.

Вот несколько советов по созданию высококачественных исправлений:

Убедитесь, что исправление не отменяет результат (первый аргумент diff обычно исходный файл, второй аргумент — изменённый файл). Убедитесь, что вы протестировали своё исправление, применив его с помощью git am или программы patch перед отправкой. Старайтесь придерживаться того же стиля, что и код, который вы пытаетесь исправить. Убедитесь, что ваше исправление действительно работает (make test, если объект, который вы исправляете, покрыт набором тестов Perl).

Можно ли использовать perlbug для отправки благодарственной записки?

Да, вы можете сделать это, используя параметр -T или вызвав программу как perlthanks. Благодарственные записки — это хорошо. Это вызывает улыбку.

Пожалуйста, сделайте заголовок вашей проблемы информативным. «Ошибка» неинформативно. Точно так же, как и «Perl падает» или «ПОМОГИТЕ!!!». Это не помогает. Лаконичное описание проблемы подойдет.

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

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

Вы можете обновить тикет о вашей ошибке на https://github.com/Perl/perl5/issues, если выпущена новая версия Perl, и ваша ошибка все еще присутствует.

ПАРАМЕТРЫ

-a

Адрес для отправки отчета вместо сохранения в файл.

-b

Тело отчета. Если не указано в командной строке или в файле с -f, у вас будет возможность отредактировать отчет.

-C

Не отправлять копию администратору при отправке отчета по почте.

-c

Адрес для отправки копии отчета при отправке отчета по почте. По умолчанию используется адрес локального администратора Perl (записанный при сборке Perl).

-d

Режим данных (по умолчанию, если вы перенаправляете или подключаете вывод). Это выводит данные вашей конфигурации без сохранения или отправки по почте. Вы можете использовать это с -v, чтобы получить более полные данные.

-e

Редактор для использования.

-f

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

-F

Файл для вывода результатов. По умолчанию используется perlbug.rep.

-h

Выводит краткое описание параметров.

-ok

Сообщить о успешной сборке на этой системе разработчикам Perl. Принудительно включает -S и -C. Принудительно устанавливает значения для -s и -b. Запрашивает адрес возврата только если не может его определить (для использования с make). Учитывает адрес возврата, указанный с помощью -r. Вы можете использовать это с -v, чтобы получить более полные данные. Создаёт отчет только если система существует меньше 60 дней.

-okay

Аналогично -ok, но будет сообщать об отчётах на более старых системах.

-nok

Сообщить об неудачной сборке на этой системе. Принудительно включает -C. Принудительно устанавливает значение для -s, затем требует редактирования отчета и указания, что пошло не так. В качестве альтернативы, подготовленный отчет может быть предоставлен с помощью -f. Запрашивает адрес возврата только если не может его определить (для использования с make). Учитывает адрес возврата, указанный с помощью -r. Вы можете использовать это с -v, чтобы получить более полные данные. Создаёт отчет только если система существует меньше 60 дней.

-nokay

Аналогично -nok, но будет сообщать об отчётах на более старых системах.

-p

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

-r

Ваш адрес возврата. Программа запросит подтверждение своего значения по умолчанию, если вы не используете этот параметр.

-S

Сохранить или отправить отчет без запроса подтверждения.

-s

Тема, которая должна быть включена в отчет. Вам будет предложено её указать, если вы не укажете её в командной строке.

-t

Режим тестирования. Позволяет управлять Perlbug из канала или файла в целях тестирования.

-T

Отправить благодарственное письмо вместо отчета об ошибке.

-v

Включить подробные данные конфигурации в отчет.

АВТОРЫ

Kenneth Albanowski (<kjahds@kjahds.com>), впоследствии доработан Gurusamy Sarathy (<gsar@activestate.com>), Tom Christiansen (<tchrist@perl.com>), Nathan Torkington (<gnat@frii.com>), Charles F. Randall (<cfr@pobox.com>), Mike Guy (<mjtg@cam.ac.uk>), Dominic Dunlop (<domo@computer.org>), Hugo van der Sanden (<hv@crypt.org>), Jarkko Hietaniemi (<jhi@iki.fi>), Chris Nandor (<pudge@pobox.com>), Jon Orwant (<orwant@media.mit.edu>, Richard Foley (<richard.foley@rfi.net>), Jesse Vincent (<jesse@bestpractical.com>) и Craig A. Berry (<craigberry@mac.com>).

СМОТРИТЕ ТАКЖЕ

perl(1), perldebug(1), perldiag(1), perlport(1), perltrap(1), diff(1), patch(1), dbx(1), gdb(1)

НЕДОСТАТКИ

Неизвестно (наверняка для их отслеживания использовалось что-то другое?)