Предоставление отчета о проблеме


Вы можете возразить, что эту тему следовало бы обсудить в главе 1 «Как получить помощь». Название отчет о проблеме (Problem Report, PR) впечатляет, не правда ли? Своим отчетом о проблеме вы не только сообщаете о своей проблеме, но и доказываете, что это у FreeBSD проблемы. Да, я сказал, доказываете. Не то чтобы FreeBSD тут ни при чем, пока вина не доказана, но вы должны предоставить полный отчет о проблеме, чтобы доказать свое утверждение. Если в отчете нет достаточных доказательств, он будет закрыт с краткой пометкой: «не ошибка» или «бесполезный отчет». Лучший форум, где вы сможете позвать на помощь, — это поисковая система, или даже список рассылки FreeBSD-questions@FreeBSD.org.

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

Наконец, отчет о проблеме подразумевает готовность к сотрудничеству. Отправляя свой отчет, вы тем самым показываете свою готовность трудиться вместе с разработчиками FreeBSD над решением проблемы. Это может означать наложение заплаток, использование различных команд или запуск команд отладки и отправку вывода разработчикам. Представляя отчет о проблеме, не следует ждать ответа «Исправлено, сделайте так-то и так-то» — это просто нереально. Если вы не готовы работать с командой разработчиков, не создавайте отчет. Конечно, наличие достаточного объема информации в отчете поможет решить проблему гораздо быстрее. Если вы сможете включить в отчет все, что необходимо разработчику, ответ придет намного быстрее.

Повторяйте за мной: «Свободное программное обеспечение. Бесплатная поддержка». Помните это, когда ваш драйвер карты RAID заставляет жесткие диски отбивать барабанную дробь.

И, наконец, было бы лучше, если при подаче отчета о проблеме у вас была установлена последняя версия FreeBSD. Может, кто-то и заглянет в отчет о проблеме для версии FreeBSD, вышедшей один или два выпуска тому назад, но никто не будет смотреть отчет для FreeBSD 2.2-stable.

Что не является отчетом о проблеме?

Любые вариации на тему «Я не знаю, как это получилось» не должны входить в отчет о проблеме. Сюда же: «FreeBSD работает совсем не так, как мне хотелось бы» или «Когда я делаю какую-нибудь глупость, происходит какая-нибудь неприятность». Если вы сломаете руку, больница примет вас независимо от того, какую глупость вы совершили, но команда FreeBSD намного разборчивее. Точно так же отчетом о проблеме не являются любые вариации на тему «Меня не устраивают версии программ, включенных в состав FreeBSD». Проект FreeBSD, например, не спешит добавить обновление компилятора до самой последней версии в ту же секунду, как только он появится, и обновление для данной конкретной версии компилятора может так никогда и не появиться. Подобные решения всегда основаны на веских причинах. Если вы открыли отчет о проблеме, только чтобы поплакаться на эту тему, в ответ вы ничего не получите, разве только комментарий «Устанавливайте из портов», и отчет тут же будет закрыт.

Перед подачей отчета о проблеме

В идеале, вам никогда не придется заполнять отчет о проблеме. Правильно созданный отчет — это большой труд не только для вас, но и для разработчиков. В проекте FreeBSD имеется отдельный список рассылки, который содержит базу данных с примерами отчетов и может использоваться как руководство по их составлению. Отправляя письмо в почтовую рассылку FreeBSD, вы объявляете о своей беде тысячам людей; создавая отчет о проблеме, вы не только объявляете о своей беде тысячам людей, но и требуете, чтобы они отреагировали на это. Прежде чем отправлять отчет о проблеме, вы должны быть абсолютно уверены, что это нужно и вам, и проекту FreeBSD.

Для начала представьте себе, что ваша проблема не уникальна, и поищите ее решение в обычных ресурсах FreeBSD. Посмотрите FAQ и Руководство. Поищите в Интернете и в архивах почтовой рассылки тех, кто уже сталкивался с подобной проблемой. Загляните в систему отчетов, нет ли там открытого отчета по этой проблеме. Затем задайте вопрос в почтовой рассылке FreeBSD-questions@FreeBSD.org, возможно, кто-то уже оказывался в подобной ситуации. Может быть, решение проблемы уже на подходе, или вам все же придется открыть новый отчет? Вопросы о вашей проблеме, которые будут вам задавать, окажут неоценимую помощь в устранении этой проблемы и в создании отчета.

Прежде чем открыть отчет, соберите всю информацию, которая может быть полезна. Сюда входят:

  • Полный протокол загрузки системы
  • Версия системы
  • Изменения в конфигурации ядра (если таковые имеются)
  • Вывод отладчика

Поддается ли проблема воспроизведению? Чтобы исследовать проблему, разработчикам нужно воспроизвести эту ситуацию. Если ваш сервер начал напевать мелодии в 3 часа ночи — это проблема. Если это случилось всего один раз, и вы не можете воспроизвести ситуацию, то лучше держите рот на замке, и никто не заподозрит, что вы псих. Однако если это происходит всякий раз, когда вы запускаете определенную комбинацию команд на определенных аппаратных средствах, проблему можно будет проверить и исследовать — и либо она будет решена, либо какая -нибудь студия звукозаписи предложит вашему серверу подписать контракт.

Для работы с PR система FreeBSD использует GNATS — хорошо зарекомендовавшую себя систему отслеживания ошибок. И хотя есть более новые и блистательные системы, ни одна из них не удовлетворяет требованиям Проекта FreeBSD. Прежде чем отправить свой отчет о проблеме, загляните в существующую базу отчетов, чтобы увидеть, что включается в отчеты о проблеме. Найти базу данных отчетов можно по адресу http://www.freebsd.org/support.html. Посмотрите, есть ли в базе данных отчеты о проблемах, похожих на вашу? Есть ли какие-либо комментарии к этим отчетам? Как насчет вывода отладчика? Можете ли вы указать на другой отчет и сказать, что они могут быть связаны? Или, может быть, другой отчет точно соответствует вашей проблеме, и вы сможете использовать информацию из него?

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

Плохие отчеты о проблемах

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

При загрузке FreeBSD 6,2-REL с образа ISO я не могу получить экран «Welcome to FreeBSD!» с пунктами меню. Меню загрузки зависает и при каждом обновлении экрана оно останавливается на 10. Какие бы клавиши я ни нажимал, загрузка не продолжается. Если я нажимаю сразу несколько клавиш, я в конечном итоге получаю панику. Если загрузка с того же самого образа ISO происходит в VMWare, появляется обратный отсчет времени, и я получаю возможность установить его в раздел диска. Я также пробовал включать/отключать в BIOS поддержку клавиатуры USB, но без успеха.

Отчет включает в себя в себя номер модели материнской платы, клавиатуры и мыши. Инструкция по воспроизведению проблемы рекомендовала загрузить ISO-образ в аналогичной конфигурации аппаратного обеспечения.

Прежде всего, у читателя, безусловно, проблема с FreeBSD. (Могут ведь и у FreeBSD быть проблемы.) У меня нет никаких сомнений в том, что система действительно зависает при загрузке именно так, как описано. Но в отчете нет никаких доказательств и никакой диагностической информации. Воспроизведение этой ситуации не имеет никакого смысла; если бы каждый установочный компакт-диск с версией FreeBSD 6.2 вел себя подобным образом на таких распространенных аппаратных средствах, как эти, команда разработчиков никогда бы не приняла его к выпуску.

Описание марки и модели оборудования не является столь полезным, как можно было бы подумать. Изготовители иногда вносят изменения в чипсеты, не изменяя номер модели. Протокол загрузки содержит подробную информацию о фактическом аппаратном окружении, так что номер модели указывать не требуется.

Если бы я столкнулся с таким поведением, то сначала бы попытался записать второй компакт-диск. Возможно, первый диск был записан с ошибками. Если ситуация повторится, я бы загрузил ISO-образ FreeBSD 6.1. Если бы попытка загрузиться с этого образа также оказалась неудачной, я бы обратился к почтовой рассылке -questions@ за получением «дальнейшей консультации перед подачей отчета о проблеме». Если бы мне удалось установить FreeBSD 6.1, а 6.2 не удалось, я включил бы в свой отчет о проблеме подробную информацию о ядре и протокол загрузки версии 6.1. Я также включил бы ссылку на архив почтовой рассылки, где обсуждалась моя проблема.

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

В FAQ системы FreeBSD есть шутка Дэга Эрлинга С. Сморграва (Dag Erling С. Smorgrav): «Сколько пользователей -current требуется, чтобы заменить электрическую лампочку»? Ответ — одна тысяча, сто и шестьдесят девять, при этом «три пользователя должны представить отчеты об этой проблеме, причем один из отчетов отнесен к категории doc и содержит единственное слово «темно»». Если проблема сводится к диагнозу «темно», то это плохой отчет о проблеме.

Хорошие отчеты о проблемах

Отправить свой отчет о проблеме можно с помощью веб-интерфейса, но я нахожу этот способ довольно неуклюжим. Если вам нравится графический интерфейс, можете попробовать gtk-send-pr (/usr/ports/sysutils/gtk-send-pr). Для создания отчетов я всегда использую send-pr(1). На мой взгляд, программа send-pr(1) позволяет сконцентрироваться на создании отчета и даже вернуться к нему спустя некоторое время, когда появится возможность заняться им. Работа над отчетом начинается с вывода шаблона формы в файл с помощью ключа -P:

# send-pr -P > problemreport.txt

Теперь можно открыть отчет об проблеме в текстовом редакторе. Вот образец шаблона:

И веб-интерфейс, и текстовая форма имеют одни и те же поля; труднее заполнить форму правильно. Шаблон включает в себя несколько строк, начинающихся с SEND-PR, которые send-pr(1) удалит из формы в процессе отправки. Любой текст в угловых скобках (< и >) является комментарием, и send-pr(1) также удалит его. В угловых скобках шаблона перечислены допустимые варианты ответов. Выберите один из них.

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

To: (Кому)
Это поле адреса электронной почты базы данных отчетов FreeBSD. Оставьте его без изменений.

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

cc: (скрытая копия)
Возможно, вы хотите отправить копию отчета кому-то еще. Например, мой босс чувствует себя лучше, имея копии отчетов о проблемах, которые он считает критическими.

X-send-pr-version, X-GNATS-Notifу, Submitter-Id:
Оставьте эти поля без изменений.

Originator: (Источник)
Это ваше имя. Обычно оно берется из системного окружения. Некоторые пользователи скрываются под псевдонимами, но я рекомендую указать здесь свое настоящее имя. Трудно подходить к серьезной проблеме с должным вниманием, если вы скрываетесь под именем «Mr. Ticklebottoms».

Organization: (Организация)
Это поле не используется, поэтому вы можете написать здесь все, что хотите.

Confidential: (Конфиденциально)
GNATS — это общедоступная база данных, и вы никогда не должны вносить конфиденциальную информацию в отчет о проблеме. Изменение значения в этом поле приведет к тому, что send-pr откажется посылать отчет. Если вы считаете, что обнаружили ошибку, относящуюся к безопасности, напишите письмо по адресу security-officer@FreeBSD.org. Однако не поступайте так только из-за того, что в отладочную информацию включен пароль root.

Synopsis: (Краткий обзор)
Это самая важная строка в отчете. Дайте краткое, однострочное описание проблемы. Разработчики именно по этой строке определяют, каким отчетам уделить свое внимание. Отчет с описанием «Моя система не работает!» будет закрыт или проигнорирован, а сообщение «Паника при большой нагрузке, отладочный дамп прилагается» имеет больше шансов привлечь внимание опытных специалистов. Если у вас есть заплатка для устранения проблемы, поместите слово PATCH (заплатка) в начало описания, такому отчету почти гарантирован быстрый ответ. Учтите, они могут признать заплатку негодной, но они посмотрят ее.

Severity: (Сложность)
Это поле может иметь одно из трех значений: non-critical (некритично), serious (серьезно) или critical (критично). Выберите из них наиболее подходящее. Критичные проблемы затрагивают каждого пользователя FreeBSD. Серьезные проблемы затрагивают пользователей определенного драйвера устройства или определенного окружения. Все остальное является некритичным. Если вы заслужите репутацию пользователя, представляющего мелкие ошибки как критичные, очень скоро ваши отчеты будут игнорироваться. Здесь все построено на честности, и репутация значит намного больше, чем можно подумать.

Priority: (Приоритет)
Вы можете ввести одно из трех значений: low (низкий), medium (средний) или high (высокий). Поле приоритета долгое время использовалось неправильно, теперь потеряло свою значимость и не принимается в учет. Я рекомендую использовать значение low или medium.

Category: (Категория)
Следует указать один из вариантов, перечисленных в области комментариев в верхней части формы отчета. Категории включают такие типы, как ports, www, docs, bin, kern и misc. Выберите категорию, к которой относится ваша проблема. Я обычно использую kern для отчетов о проблемах с ядром, bin для проблем, связанных с приложениями пространства пользователя, ports для описания проблем с «портами» и doc для проблем с документами.

Class: (Класс)
Это тип проблемы. Если вы столкнулись с аварийным отказом программы или системы, укажите класс sw-bug.

Release: (Выпуск)
send-pr(1) автоматически внесет тип вашей системы в поле Release. Если вы заполняете отчет не в той системе, где проявляются неполадки, укажите верное значение этого поля.

Environment: (Окружение)
Поместите сюда вывод команды uname -а. В это поле можно добавить дополнительную информацию о своей машине. Например, если машина — это веб-сервер, испытывающий тяжелые нагрузки, укажите это. Если у вас есть фрагмент конфигурационного файла, позволяющий воспроизвести панику, поместите его сюда. Раздел Environment должен быть очень кратким. Возможно, для вас будет желательно скрыть имя машины по соображениям безопасности.

Description: (Описание)
Поле Description — это текстовый раздел, где в свободной форме можно подробно описать проблему. Не разглагольствуйте и не говорите бессвязно, а просто опишите, что случилось. Если можно получить дамп паники, сделайте это и разместите здесь вывод отладчика. Кроме того, разместите в этом поле конфигурацию ядра и подробный протокол загрузки.

How-To-Repeat: (Как воспроизвести)
Дайте здесь краткие инструкции о том, как воспроизвести проблему. Для некоторых отчетов вполне подойдет предложение: «Прочитайте архив рассылки FreeBSD-questions за неделю и посмотрите, как часто это встречается», особенно если речь идет об изменениях в документации. Более специфичные проблемы требуют большего количества информации.

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

Комментарии запрещены.