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. Убедитесь, что проблема, с которой вы столкнулись, не является преднамеренной, просмотрев документацию, поставляемую с дистрибутивом 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)

ОШИБКИ

Неизвестны (как вы думаете, что было использовано для их сообщения?)