Составление сообщений о проблеме во FreeBSD

4.1. Как писать хорошие сообщения о проблемах

• Основным языком общения разработчиков FreeBSD является английский. База данных по проблемам также ведется на английском. Если вы испытываете проблемы с формулировкой описания проблемы по-английски, свяжитесь со своими соотечественниками, которые помогут вам составить PR.

• Не оставляйте поле ''Synopsis'' (краткое описание) пустым. Сообщения о проблемах попадают как в списки рассылки, которые затем расходятся по всему миру (в них поле ''Synopsis'' определяет тему письма), так и в базу данных. Просматривающий эту базу, как правило, пройдет мимо PR с пустым кратким описанием. Не забудьте, что PR остается в базе до тех пор, пока кто-либо не закроет его; сообщение-аноним, скорее всего, просто потеряется на общем фоне.

• Избегайте туманных описаний в поле ''Synopsis''. Не стоит предполагать, что читающий ваше сообщение владеет контекстом; поэтому, чем подробнее вы опишете ситуацию, тем лучше. В частности, к какой части системы относится ваша проблема? Проявляется ли она на этапе установки или во время нормальной работы? Например, вместо строки Synopsis: portupgrade is broken следовало бы написать что-то вроде Synopsis: port ports-mgmt/portupgrade coredumps on -current. В случае портированных приложений в поле ''Synopsis'' полезно указывать не только имя порта, но и категорию.

• Если у вас есть готовый патч, скажите об этом. PR, содержащий патч, имеет куда больше шансов быть рассмотренным. В этом случае добавьте строку [patch] (включая квадратные скобки) в начало поля ''Synopsis'' (хотя использование именно этой формы необязательно, она является стандартом де-факто).

• Если вы отвечаете за исходные тексты, сообщите об этом. Если вы отвечаете за часть исходных текстов (например, порт), вы можете добавить в начало поля ''Synopsis'' строку [maintainer update] (включая квадратные скобки), а также установить класс вашего PR (поле ''Class'') в maintainer-update. В этом случае коммиттеру, обрабатывающему ваш PR, не придётся лишний раз проверять.

• Будьте точны в формулировках. Чем больше информации вы можете предоставить о проблеме, тем больше у вас шансов получить ответ.

  • Включите информацию о версии FreeBSD, которую вы используйте (существует специальное поле для его включения, смотрите ниже) и на какой архитектуре. Сообщите, используете ли вы release версию (установили с компакт-диска либо загрузили) или скачали её с помощью Subversion (и если так, то сообщите номер ревизии). Если вы используете FreeBSD-CURRENT, то первый вопрос, который вам могут задать, будет про номер ревизии, так как исправления для этой ветки (особенно в случае серьёзных проблем) имеют тенденцию появляться слишком быстро.

  • Включите информацию о том, какие глобальные опции вы указали в make.conf. На заметку: Объявление опций наподобие -02 и других, описанных в gcc(1) во многих случаях может быть причиной ошибок. Хотя и разработчики FreeBSD будут принимать патчи, у них не будет желания исследовать такие случаи из-за отсутствия времени и добровольцев, и вместо этого они могут ответить, что это не поддерживается.

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

  • Если ваша проблема связана с ядром, будьте готовы предоставить следующую информацию (вам не обязательно включать её всю, она пойдёт лишь на заполнение базы данных, но вы должны включить информацию, которая по вашему мнению актуальна):

    • Вашу конфигурацию ядра, включая то, какие устройства у вас установлены

    • Включены ли у вас опции отладки (например, WITNESS), и если так, то существует ли проблема после изменения значения этой опции

    • Полный вывод обратной трассировки (backtrace), паники или иного консольного вывода, или же записи из /var/log/messages, если они были сгенерированы

    • Вывод команды pciconf -l, а также соответствующие части вывода dmesg, в случае, если проблема связана с конкретным оборудованием

    • Прочли ли вы src/UPDATING, описана ли там ваша проблема (кто-нибудь спросит обязательно)

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

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

    • Какие порты вы устанавливали

    • Имеются ли какие-либо переменные окружения, которые переписывают первоначально-установленные в bsd.port.mk, такие как, PORTSDIR)

    • Прочли ли вы ports/UPDATING, и описана ли там ваша проблема (кто-нибудь спросит обязательно)

• Избегайте нечетких запросов о новых возможностях. Сообщение типа ''кто-то обязательно должен сделать так, чтобы такая-то утилита вела себя так-то'' имеет куда меньше шансов встретить позитивный отклик, чем более четко сформулированный запрос. Помните, что исходные тексты доступны всем, так что если вам нужна реализация какого-то нового свойства, лучший способ— взяться за работу самому! Не забудьте также, что такие моменты лучше обсуждать в списках рассылки, таких как freebsd-questions, чем делать это посредством базы данных PR.

• Убедитесь, что ваша проблема еще никем не описана. Мы уже говорили об этом, но стоит повториться. Потратьте пару минут на составление запросов к базе PR: http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query. (Несмотря на повторы, об этом постоянно забывают)

• Сообщайте об одной проблеме в одном PR. Избегайте описания двух и более проблем в одном сообщении (исключением являются взаимосвязанные проблемы). Оформляя патчи, не пытайтесь в них добавлять множество функциональных возможностей или исправлять ими несколько ошибок в одном и том же сообщении о проблеме (опять же, за исключением взаимосвязанных проблем) — для таких PR-ов потребуется значительно больше времени на обработку.

• Избегайте полемики. Если ваше сообщение касается области или способов реализации, которые ранее вызвали разногласия, вам стоит быть готовым предоставить не только патчи, но и внятные аргументы, почему следует поступать именно так (то есть, это ''Правильный Путь''). Как отмечалось выше, аккуратный поиск по архиву списков рассылки http://www.FreeBSD.org/search/search.html#mailinglists никогда не помешает.

• Будьте вежливы. Почти каждый из тех, кто может заниматься вашим сообщением, является добровольцем. Никому не понравятся указания, как и что делать, когда он и так занимается этим, да еще и по каким-либо причинам, отличным от финансовых. Вообще говоря, этого подхода следует придерживаться, имея дело с любым проектом с Открытыми Исходными текстами (Open Source).

4.2. Прежде всего

Если вы используйте утилиту send-pr(1) проверьте, что переменная вашего окружения VISUAL (или EDITOR, если VISUAL не задана) задана подходящим образом.

Следует также проверить работоспособность системы электронной почты. Утилита send-pr(1) использует почтовую систему для отправки и отслеживания сообщения о проблеме. Если с машины, на которой вы запускаете send-pr(1), нельзя отправить почту, сообщение не попадёт в базу данных GNATS. О настройке электронной почты во FreeBSD можно прочитать в главе ''Электронная почта'' Руководства по FreeBSD по адресу http://www.FreeBSD.org/doc/ru_RU.KOI8-R/books/handbook/mail.html.

Убедитесь, что ваш почтовый клиент не исказит сообщение по пути в GNATS. В частности, если ваш почтовый клиент автоматически переносит строки, изменяет символы табуляции на пробелы или предотвращает интерпретацию символов новой строки, любой патч, который вы пришлёте окажется непригодным. Для текста мы хотели бы, чтобы вы делали строчки размером примерно в 70 символов для читабельности PR на веб странице.

Примерные соображения должны учитываться при отправке сообщения об ошибке через веб-форму вместо send-pr(1). Помните, что операции копирования-вставки могут иметь сторонние эффекты в форматировании текста. В определённых случаях может быть необходимо использовать uuencode(1) для гарантии того, что патчи придут не изменёнными.

И наконец, если ваше сообщение будет объёмным, вы должны приготовить его в offline, чтобы ничего не потерялось в случае, если будет проблема при его отправке. Это особенно касается веб-формы.

4.3. Вложение патчей или файлов

Нижеследующее применимо к передаче сообщения о проблеме посредством электронной почты:

Программа send-pr(1) предусматривает присоединение файлов к сообщению о проблеме. Вы можете вложить сколько угодно файлов, но каждый с уникальным именем (имеется в виду имя файла без маршрута). Просто используйте параметр командной строки -a для задания имен файлов, которые вы хотите присоединить:

% send-pr -a /var/run/dmesg -a /tmp/errors

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

Если вы вкладываете патч, обязательно используйте параметр -c или -u вместе с командой diff(1) для создания контекстного или унифицированного diff-файла (унифицированный формат предпочтителен), и обязательно укажите точные номера SVN ревизий файлов, которые вы изменяли, чтобы разработчики, которые будут читать ваше сообщение, смогли легко его применить. Для проблем, связанных с ядром или с базовыми утилитами, предпочтительнее будет патч относительно ветки FreeBSD-CURRENT (или Subversion-ветки HEAD), так как весь новый код должен быть сначала протестирован в ней. После завершения тестирования код будет интегрирован в ветвь FreeBSD-STABLE.

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

Не отсылайте патчи в виде вложений, используя Content-Transfer-Encoding: quoted-printable. Это выполнит экранирование (escaping) символов и весь патч будет бесполезным.

Следует также заметить, что включение небольших патчей в сообщение о проблеме является приемлемой практикой, в особенности если они решают проблему, описанную в сообщении, большие же патчи, а в особенности новый код, который может требовать значительного просмотра перед тем, как он будет внесен в дерево исходных текстов, должны быть размещены на web- или ftp-сервере, а в сообщение о проблеме должен быть включён только URL указывающий на этот патч. Очень часто патчи, пересылаемые по электронной почте, а в особенности если задействована GNATS, бывают искажены, и, как следствие, чем больше патч, тем труднее будет для заинтересованных людей привести его к нормальному виду. Также то, что патч будет размещён отдельно от сообщения о проблеме, даёт возможность изменять его не отсылая полный патч в дополнение к изначальному сообщению о проблеме. И наконец, большие патчи просто увеличивают размер базы данных, так как закрытые сообщения об ошибках на самом деле не удаляются, а сохраняются и помечаются, как closed.

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

4.4. Заполнение шаблона

Следующие несколько абзацев применимы только к способу подачи PR через электронную почту:

После запуска утилиты send-pr(1) вам будет представлен шаблон сообщения о проблеме. Шаблон состоит из списка полей, некоторые из которых уже заполнены, а некоторые содержат комментарии, объясняющие назначение поля или перечисляющие подходящие значения. Не беспокойтесь о комментариях; они будут автоматически удалены, если вы их не изменяли (или удалите их сами).

Вверху шаблона, ниже строк SEND-PR: находятся заголовки почтового сообщения. Вам обычно не нужно их изменять, если только вы не посылаете сообщение о проблеме с машины или от учетной записи, которая может посылать, но не может получать электронную почту, в случае чего вы можете задать в полях From: и Reply-To: ваши реальные адреса электронной почты. Вы можете также послать самому себе (или кому-то еще) копию сообщения о проблеме, добавив один или большее количество адресов к заголовку Cc:.

В шаблоне вы найдете два однострочных поля:

• Submitter-Id: Не меняйте его. Значение по умолчанию current-users правильно, даже если вы используете FreeBSD-STABLE.

• Confidential: Предварительно заполнено как no, его изменение не имеет значения, так как нет такого понятия, как конфиденциальное сообщение о проблеме — база данных PR распространяется по всему миру.

Далее описаны общие поля для почтового и веб интерфейса:

• Originator: Пожалуйста, укажите ваше реальное имя, за которым опционально следует адрес вашей электронной почты в угловых скобках. Обычно, send-pr(1) заполняет поле Originator содержимым поля gecos из учетной записи текущего пользователя.

  Замечание: Предоставленный вами адрес электронной почты станет публичной информацией и может стать доступным спамерам. Поэтому совсем не лишними будут меры по борьбе со спамом на вашей стороне, или же можно воспользоваться временным адресом электронной почты. Однако, если вы укажете несуществующий почтовый адрес, то у нас не будет возможности уточнять детали по вашему PR.

• Organization: Все, что вы захотите здесь указать. Это поле не содержит значительной информации.

• Synopsis: Заполняется кратким и точным описанием проблемы. Краткое описание используется в качестве темы сообщения электронной почты о проблеме, и используется при выдаче списков и выборках сообщений о проблемах; сообщения о проблемах с непонятными краткими описаниями чаще всего игнорируются.

  Повторим: если к вашему сообщению о проблеме приложен патч, то, пожалуйста, начните краткое описание с [patch] (включая квадратные скобки); если PR принадлежит к категории ports и вы являетесь его мейнтейнером, то начните описание с [maintainer update] (включая квадратные скобки) и установите класс проблемы (поле ''Class'') в maintainer-update.

• Severity: Одно из non-critical, serious или critical. Не переусердствуйте; избегайте пометки вашей проблемы как critical, если только это не действительно критичная проблема (повреждение данных, существенная потеря функциональности в -CURRENT), или serious, если только это не касается многих пользователей (паники ядра, блокировки (freezes), проблемы с конкретными драйверами устройств или с системными утилитами). Разработчики FreeBSD не обязательно будут работать над вашей проблемой быстрее, если вы установите слишком высокий уровень важности, т.к. существует много других людей, которые сделали тоже самое — некоторые разработчики всё же уделят этому полю немного внимания и перейдут к следующему сообщению именно из-за этого поля.

  Замечание: Большинство проблем с безопасностью не следует отправлять в GNATS, потому что вся эта информация становится публичной. Пожалуйста, направляйте подобные отчеты на электронный адрес Группа Офицеров Безопасности <security-officer@FreeBSD.org>.

• Priority: Одно из low, medium или high. high должен использоваться для проблем, которые затронут конкретно каждого пользователя FreeBSD, а medium для чего-то, что затронет многих пользователей.

  Замечание: Ввиду массовых злоупотреблений это поле потеряло свое значение.

• Category: Выберите соответствующую категорию.

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

  Вот описание основных категорий:

  • Если проблема в ядре, в библиотеках (таких как стандартная библиотека С libc) или в драйвере из базовой системы, то используйте категорию kern. (Есть несколько исключений, описанных ниже). В общем, это всё, что описано в разделах 2, 3 или 4 справочника.

  • Если проблема с бинарной программой, например с sh(1) или mount(8), то вам прежде всего необходимо определить принадлежность программы к базовой системе или к установке из коллекции портов. Если вы не уверены, выполните команду whereis имя программы. В FreeBSD для коллекции портов существует договоренность: установка ведется в /usr/local, однако это может быть переопределено системным администратором. Для таких программ следует использовать категорию ports (даже если категория порта www; см. ниже). Если программа располагается в /bin, /usr/bin, /sbin или в /usr/sbin, то это часть базовой системы, и вам следует использовать категорию bin. (Несколько программ, например gcc(1), на самом деле используют категорию gnu, но не беспокойтесь об этом сейчас.) Программы этой категории описаны в разделах 1 и 8 справочной системы.

  • Если вы уверены, что в стартовых скриптах (rc) или в каком-то ином неисполняемом конфигурационном файле присутствует ошибка, тогда верной категорией будет conf (configuration). Эти сущности описываются в разделе 5 справочной системы.

  • Если вы нашли проблему в наборе документации (статьи, книги, страницы справочной системы), правильным выбором будет docs.

  • Если вы наблюдаете проблему на страницах сайта FreeBSD, то правильным выбором будет www.

    Замечание: Если проблема с чем-то из порта, называемого www/someportname , то она все же принадлежит к категории ports.

  Далее представлены более специализированные категории.

  • Если проблема принадлежит к kern, но в то же время имеет дело с подсистемой USB, то правильным выбором будет usb.

  • Если проблема принадлежит к kern и найдена в потоковых библиотеках, правильным выбором будет threads.

  • Если проблема принадлежит к базовой системе и касается соблюдения стандартов, таких как POSIX®, правильным выбором будет standards.

  • Если проблема связана с ошибками внутри Java Virtual Machine™ (JVM™), даже если Java™ была установлена из коллекции портов, вам следует выбрать категорию java. Более общие проблемы с портами Java попадают под категорию ports.

  Далее перечислены остальные категории.

  • Если вы уверены, что проблема проявляется только на используемой вами процессорной архитектуре, выберите одну из архитектурно-специфичных категорий: это i386 для Intel-совместимых машин в 32-битном режиме; amd64 для AMD машин в 64-битном режиме (сюда также входят Intel-совместимые машины работающие в режиме EMT64); и менее распространенные arm, ia64, powerpc и sparc64.

    Замечание: Люди часто ошибаются в выборе категории. Если вы не уверены в правильности выбора, то лучше не гадать, а выбрать misc.

    Пример 1. Правильное использование категории

    У вас простой ПК, и вы подозреваете, что столкнулись с проблемой, специфичной для конкретного чипсета или материнской платы: верная категория — i386.

    Пример 2. Неправильное использование категории

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

  • Если вы не знаете в чем проблема (или вам кажется, что описание не попадает ни под какую из вышеобозначенных), используйте категорию misc. Перед тем, как написать PR, можно для начала спросить помощи в Список рассылки, посвящённый вопросам и ответам пользователей FreeBSD. Возможно, там вам подскажут, какую из существующих категорий следует выбрать.

  Вот текущий перечень категорий (взят из http://svnweb.freebsd.org/base/head/gnu/usr.bin/send-pr/categories):

  • advocacy: проблемы, связанные с общественным мнением о FreeBSD. Вышло из употребления.

  • amd64: проблемы, специфичные для платформы AMD64.

  • arm: проблемы, специфичные для платформы ARM.

  • bin: проблемы с пользовательскими программами из базовой системы.

  • conf: проблемы с файлами настройки, используемыми по умолчанию значениями и прочее.

  • docs: проблемы со страницами справочной системы или онлайновой документацией.

  • gnu: проблемы с портированным программным обеспечением GNU, таким как gcc(1) или grep(1).

  • i386: проблемы, специфичные для платформы i386™.

  • ia64: проблемы, специфичные для платформы ia64.

  • java: проблемы, связанные с виртуальной машиной Java.

  • kern: проблемы с ядром или с библиотеками в базовой системе, или с драйверами устройств, не связанными с какой-либо конкретной платформой.

  • misc: все, что не подпадает ни под какую другую категорию. (Надо отметить, что нет почти ничего, чтобы действительно соответствовало этой категории, за исключением проблем с релизами и с инфраструктурой сборки. Временные отказы при построении ветки HEAD не принадлежат к данной категории. Также надо отметить, что проблемы этой категории имеют тенденцию теряться легче всего).

  • ports: проблемы, связанные с коллекцией портов.

  • powerpc: проблемы, специфичные для платформы PowerPC®.

  • sparc64: проблемы, специфичные для платформы Sparc64®.

  • standards: проблемы, связанные с соответствием стандартам.

  • threads: проблемы, касающиеся реализации тредов во FreeBSD (особенно во FreeBSD-CURRENT).

  • usb: проблемы, относящиеся к реализации USB во FreeBSD.

  • www: изменения или улучшения сайта FreeBSD

• Class: Выберите одно из следующего:

  • sw-bug: ошибки в программном обеспечении.

  • doc-bug: ошибки в документации.

  • change-request: запросы на расширение функций или изменение в существующих.

  • update: обновления портов или другого программного обеспечения сторонних разработчиков.

  • maintainer-update: обновления в портах, для которых вы являетесь ответственной персоной.

• Release: Используемая вами версия FreeBSD. Оно заполняется автоматически программой send-pr(1) и требует изменения, если только вы отсылаете сообщение о проблеме с системы, отличающейся от той, где вы столкнулись с проблемой.

И наконец, последовательность многострочных полей:

• Environment: Оно должно максимально точно описывать окружение, в котором встречается проблема. Сюда включается версия операционной системы, версия конкретной программы или файла, содержащего проблему, и любая другая информация, такая, как конфигурация системы, другое программное обеспечение, которое влияет на проблему, и так далее—просто все, что разработчик должен знать для создания условий появления проблемы.

• Description: Полное и точное описание проблемы, с которой вы столкнулись. Попытайтесь избежать своих предположений о причинах проблемы, если только вы не уверены, что правы, так как вы можете привести разработчика к неправильным предположениям о проблеме.

• How-To-Repeat: Последовательность действий, которые должны быть выполнены для повторения проблемы.

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

4.5. Отправка сообщения о проблеме

Если вы используете send-pr(1):

Как только вы заполните шаблон, сохраните его и выйдете из редактора, send-pr(1) запросит вас s)end, e)dit or a)bort?. Вы можете нажать s для продолжения и отправки сообщения о проблеме, e для повторного запуска редактора и выполнения дальнейших изменений, или a для отказа от вашего сообщения. Если вы выберете последнее, то ваше сообщение о проблеме останется на диске (send-pr(1) укажет вам имя файла перед завершением работы), так что вы сможете отредактировать его на свой вкус или передать в систему с лучшим подключением к сети, перед тем, как послать его при помощи параметра -f программы send-pr(1):

% send-pr -f ~/my-problem-report

При этом будет прочитан указанный файл, будет проверено содержимое, убраны комментарии и сообщение будет отослано.

Если вы используете веб форму:

Перед нажатием submit вам потребуется заполнить проверочное поле текстом, представленным на картинке рядом. Эта непопулярная мера была принята в связи со злоупотреблениями со стороны роботов и некоторых неверно сориентированных индивидуумов. Это необходимая мера, которая никому не нравится, и, пожалуйста, не просите нас убрать её.

Отметим, что вам настоятельно рекомендуется сохранить вашу работу (PR) куда-нибудь перед нажатием кнопки submit. Распространенная пользовательская ошибка: отображение браузером устаревшей проверочной картинки из его кэша. Если это произойдет в вашем случае, ваше сообщение будет отвергнуто и ваши труды пропадут.

Если по какой-либо причине вы не имеете возможности видеть проверочную картинку, а также не можете воспользоваться send-pr(1), пожалуйста примите наши извинения за неудобства и пришлите ваш PR электронной почтой команде <freebsd-bugbusters@FreeBSD.org>.