perlbug

СОДЕРЖАНИЕ

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

ИМЯ

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

СИНОПСИС

perlbug

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

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

perlthanks

ОПИСАНИЕ

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

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

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

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

В крайних случаях 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, и поощряйте разработчиков добрыми словами или предложениями прохладительных напитков. (Будьте добры к разработчикам. Досаждать им или высмеивать их, вероятно, даст обратный эффект).

Вы можете обновить тикет о вашей ошибке на http://rt.perl.org, если выйдет новая версия Perl, и ошибка всё ещё присутствует.

ПАРАМЕТРЫ

-a

Адрес для отправки отчета. По умолчанию perlbug@perl.org.

-A

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

-b

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

-C

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

-c

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

-d

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

-e

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

-f

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

-F

Файл для вывода результатов вместо отправки по электронной почте. Особенно полезно при запуске perlbug на машине без прямого подключения к интернету.

-h

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

-ok

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

-okay

Как -ok, но будет сообщать об отчете об older system.

-nok

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

-nokay

Как -nok, но будет сообщать об older system.

-p

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

-r

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

-S

Отправить без запроса подтверждения.

-s

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

-t

Режим тестирования. Адрес назначения по умолчанию perlbug-test@perl.org. Также позволяет управлять 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)

ОШИБКИ

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