perlthanks

СОДЕРЖАНИЕ

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

ИМЯ

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 ] [ -A ] [ -h ] [ -T ]

perlbug [ -v ] [ -r returnaddress ] [ -A ] [ -ok | -okay | -nok | -nokay ]

perlthanks

ОПИСАНИЕ

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

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

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

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

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

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

Какая версия 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 с отладочной информацией, воспроизведите сбой и трассировку стека.

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

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

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

Если да, это отличные новости; сообщения об ошибках с исправлениями, скорее всего, получат значительно больше внимания и интереса, чем сообщения об ошибках без исправлений. Пожалуйста, прикрепите ваше исправление к сообщению, используя параметр -p. При отправке исправления, создайте его с использованием git format-patch, если это возможно, хотя унифицированная разница, созданная с diff -pu, будет почти также хорошо работать.

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

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

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

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

perlbug, помимо прочего, гарантирует, что ваш отчёт включает важную информацию о вашей версии Perl. Если perlbug не может отправить ваш отчёт после того, как вы его напечатали, вам, возможно, придётся составить сообщение самостоятельно, добавить вывод, полученный от perlbug -d, и отправить его на perlbug@perl.org. Если по какой-то причине вы не можете запустить perlbug на вашей системе, обязательно включите весь вывод, полученный от выполнения perl -V (обратите внимание на заглавную букву V).

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

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

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

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

Если вам важно, чтобы ваша ошибка была исправлена, следите за рассылкой perl5-porters@perl.org (рассылки модерируются, ваше сообщение может появиться с некоторым опозданием) и за журналами коммитов в развивающихся версиях 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)

ОШИБКИ

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