perlbug

СОДЕРЖАНИЕ

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

НАЗВАНИЕ

perlbug - как подавать сообщения об ошибках в Perl

СИНТАКСИС

perlbug

perlbug [ -v ] [ -a address ] [ -s subject ] [ -b body | -f inputfile ] [ -F outputfile ] [ -r returnaddress ] [ -e editor ] [ -c adminaddress | -C ] [ -S ] [ -t ] [ -d ] [ -h ] [ -T ]

perlbug [ -v ] [ -r returnaddress ] [ -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 5.0.

Уверены ли вы, что это действительно ошибка?

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Если да, это отличная новость; сообщения об ошибках с исправлениями, скорее всего, получат значительно больше внимания и интереса, чем сообщения без исправлений. Пожалуйста, отправьте свое исправление через GitHub Pull Request, как описано в 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)

ОШИБКИ

Известных нет (попробуйте сами отправить отчет об ошибке?)