Рекомендации по работе с сообщениями о проблемах

$FreeBSD: head/ru_RU.KOI8-R/articles/pr-guidelines/article.xml 39632 2012-10-01 11:56:00Z gabor $

$FreeBSD: head/ru_RU.KOI8-R/articles/pr-guidelines/article.xml 39632 2012-10-01 11:56:00Z gabor $

FreeBSD это зарегистрированная торговая марка FreeBSD Foundation.

Motif, OSF/1 и UNIX это зарегистрированные торговые марки, а IT DialTone и The Open Group это торговые марки Open Group в Соединенных Штатах и других странах.

Многие из обозначений, используемые производителями и продавцами для обозначения своих продуктов, заявляются в качестве торговых марок. Когда такие обозначения появляются в этом документе, и Проекту FreeBSD известно о торговой марке, к обозначению добавляется знак ''™'' или ''®''.

Это руководство описывает рекомендуемую практику обработки сообщений об ошибках FreeBSD (Problem Reports - PR). Хотя эти рекомендации предназначены для Группы поддержки базы данных сообщений о проблемах FreeBSD (PR Database Maintenance Team) , им должны следовать все, кто работает с этими сообщениями.


Содержание
1. Введение
2. Жизненный цикл сообщения о проблеме
3. Состояние сообщений о проблемах
4. Типы сообщений о проблемах
5. Дополнительная литература

1. Введение

GNATS является системой управления неисправностями (сообщениями об ошибках), которая используется в Проекте FreeBSD. Так как тщательное отслеживание заметных изъянов в программном обеспечении важно для обеспечения качества FreeBSD, правильное использование GNATS необходимо для дальнейшего развития Проекта.

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


2. Жизненный цикл сообщения о проблеме

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

Замечание: Адрес ''электронной почты'' может оказаться недоступным. В этом случае ответьте на PR обычным образом и попросите Респондента (в своём сообщении) предоставить рабочий адрес электронной почты. Обычно это происходит в случаях использования send-pr(1) в системах с выключенной или неустановленной почтовой системой.


3. Состояние сообщений о проблемах

При выполнении некоторых действий очень важно обновлять состояние PR. Это состояние должно в точности отражать текущее состояние работы над PR.

Пример 1. Маленький пример того, когда именно нужно менять состояние PR

Когда PR находится в работе и ответственный разработчик(и) удовлетворён получающимся решением, то он отвечает на PR и меняет его состояние на ''feedback''. В этот момент Респондент должен изучить исправление в своей ситуации и ответить, действительно ли был устранён дефект.

Сообщение о проблеме может находится в одном из следующих состояний:

open

Начальное состояние; проблема была поставлена и её необходимо рассмотреть.

analyzed

Проблема была рассмотрена, ищется её решение.

feedback

Дальнейшая работа требует дополнительной информации от Респондента или сообщества; возможно помещение информации о предлагаемом решении.

patched

Патч был перенесён в дерево исходных текстов, но что-то (выполнение MFC или, возможно, подтверждение Респондента) ещё требуется доделать.

suspended

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

repocopy

Решение проблемы зависит от завершения операции копирования репозитория (внутренние операции репозитория CVS).

closed

Сообщение о проблеме было закрыто, когда все изменения были перенесены, задокументированы и протестированы, либо когда исправление проблемы было отвергнуто.

Замечание: Состояние ''patched'' напрямую связано с предлагаемыми решениями, так что вы можете перейти сразу к состоянию ''closed'', если Респондент не может протестировать патч, либо на ваших тестовых прогонах он работает.


4. Типы сообщений о проблемах

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

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


4.1. Неназначенные PR

По прибытии сообщениям о проблемах устанавливаются общие назначения (generic assignee). Они всегда предваряются префиксом freebsd-. Точное название назначения (assignee) зависит от категории и в большинстве случаев оно соответствует определенному списку рассылки FreeBSD. Далее следует текущий перечень назначений (assignee), составленный в порядке от общих к частным:

Таблица 1. Назначения по умолчанию — наиболее общие

Тип Категория Назначение по умолчанию
базовая система bin, conf, gnu, kern, misc freebsd-bugs
специфичные для архитектуры alpha, amd64, arm, i386, ia64, powerpc, sparc64 freebsd-arch
коллекция портов ports freebsd-ports-bugs
документация, поставляемая с системой docs freebsd-doc
страницы сайта FreeBSD (за исключением документации) www freebsd-www

Таблица 2. Назначения по умолчанию — остальные

Тип Категория Назначение по умолчанию
в защиту FreeBSD (advocacy efforts) advocacy freebsd-advocacy
проблемы с Java Virtual Machine java freebsd-java
соответствие стандартам standards freebsd-standards
тредовые библиотеки threads freebsd-threads
подсистема usb(4) usb freebsd-usb

Не удивляйтесь, если обнаружите, что автор PR присвоил ему неправильную категорию. Если вы исправите категорию, то не забудьте также подправить и назначение. (В частности, для посылающих PR является трудностью понять, что если проблема возникает на системе с архитектурой i386, то она также может быть общей для всех архитектур FreeBSD, и поэтому более подходящей будет категория kern. Несомненно, обратное также справедливо).

Назначения некоторых PR могут быть переопределены из общих любым лицом, имеющим соответствующие привилегии. Существует несколько типов назначений: специализированные списки рассылки; почтовые алиасы (расширяемые в списки электронных адресов заинтересованных людей) и назначения отдельным лицам.

Если назначением является список рассылки, пожалуйста, выполняя переназначение, используйте длинную форму (например, freebsd-foo вместо foo); благодаря этому сообщение, посылаемое в список рассылки, не будет дублироваться.

Замечание: Так как список лиц добровольно согласившихся принимать назначения для некоторых типов PR изменяется часто, то наиболее подходящим местом для его размещения является FreeBSD wiki.

Ниже приведен (возможно, неполный) перечень назначений.

Таблица 3. Общие назначения — базовая система

Тип Предполагаемая категория Предполагаемое назначение Тип назначения
проблема, специфичная для архитектуры ARM® arm freebsd-arm список рассылки
проблема, специфичная для архитектуры MIPS® kern freebsd-mips список рассылки
проблема, специфичная для архитектуры PowerPC® kern freebsd-ppc список рассылки
проблема с Advanced Configuration and Power Management (acpi(4)) kern freebsd-acpi список рассылки
проблема с драйверами ATM kern freebsd-atm список рассылки
проблема с встраиваемой системой или минимальным дистрибутивом FreeBSD (например, NanoBSD/PicoBSD/FreeBSD-arm) kern freebsd-embedded список рассылки
проблема с драйверами FireWire® kern freebsd-firewire список рассылки
проблема в исходном коде файловой системы kern freebsd-fs список рассылки
проблема с подсистемой geom(4) kern freebsd-geom список рассылки
проблема с подсистемой ipfw(4) kern freebsd-ipfw список рассылки
проблема с драйверами ISDN kern freebsd-isdn список рассылки
подсистема jail(8) kern freebsd-jail список рассылки
проблема с эмуляцией Linux® или SVR4 kern freebsd-emulation список рассылки
проблема с сетевым стеком kern freebsd-net список рассылки
проблема с подсистемой pf(4) kern freebsd-pf список рассылки
проблема с подсистемой scsi(4) kern freebsd-scsi список рассылки
проблема с звуковой подсистемой (sound(4)) kern freebsd-multimedia список рассылки
проблема с подсистемой wlan(4) или с драйвером беспроводного устройства kern freebsd-wireless список рассылки
проблема с sysinstall(8) или с bsdinstall(8) bin freebsd-sysinstall список рассылки
проблема с системными стартовыми скриптами (rc(8)) kern freebsd-rc список рассылки
проблемы в работе VIMAGE, VNET, или проблемы в их коде kern freebsd-virtualization список рассылки
проблема с эмуляцией Xen kern freebsd-xen список рассылки

Таблица 4. Общие назначения — коллекция портов

Тип Предполагаемая категория Предполагаемое назначение Тип назначения
проблема с инфраструктурой системы портов (не с конкретным портом!) ports portmgr алиас
порт, у которого мейнтейнер apache@FreeBSD.org ports apache список рассылки
порт, у которого мейнтейнер autotools@FreeBSD.org ports autotools алиас
порт, у которого мейнтейнер doceng@FreeBSD.org ports doceng алиас
порт, у которого мейнтейнер eclipse@FreeBSD.org ports freebsd-eclipse список рассылки
порт, у которого мейнтейнер gecko@FreeBSD.org ports gecko список рассылки
порт, у которого мейнтейнер gnome@FreeBSD.org ports gnome список рассылки
порт, у которого мейнтейнер hamradio@FreeBSD.org ports hamradio алиас
порт, у которого мейнтейнер haskell@FreeBSD.org ports haskell алиас
порт, у которого мейнтейнер java@FreeBSD.org ports freebsd-java список рассылки
порт, у которого мейнтейнер kde@FreeBSD.org ports kde список рассылки
порт, у которого мейнтейнер mono@FreeBSD.org ports mono список рассылки
порт, у которого мейнтейнер office@FreeBSD.org ports freebsd-office список рассылки
порт, у которого мейнтейнер perl@FreeBSD.org ports perl список рассылки
порт, у которого мейнтейнер python@FreeBSD.org ports freebsd-python список рассылки
порт, у которого мейнтейнер ruby@FreeBSD.org ports freebsd-ruby список рассылки
порт, у которого мейнтейнер secteam@FreeBSD.org ports secteam алиас
порт, у которого мейнтейнер box@FreeBSD.org ports vbox алиас
порт, у которого мейнтейнер x11@FreeBSD.org ports freebsd-x11 список рассылки

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

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

Таблица 5. Общие назначения — остальные

Тип Предполагаемая категория Предполагаемое назначение Тип назначения
неполадки с самой GNATS(send-pr(1)) bin bugmeister алиас
неполадки с веб интерфейсом GNATS www bugmeister алиас

4.2. Назначение PR

Если в PR в заполненном поле responsible указано имя разработчика FreeBSD, это значит, что PR взята этим человеком для дальнейшей работы.

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


4.3. Повторные PR

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


4.4. Просроченные PR

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

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

  • Если PR описывает проблему, которая, как вы знаете, является результатом неправильного использования (некорректная настройка или что-то ещё), напишите отклик, в котором опишите, что автор исходного сделал не так, а затем закройте PR с описанием ''User error'' или ''Configuration error''.

  • Если в PR описывается ошибка, которая, как вы знаете, была исправлена как в -CURRENT, так и -STABLE, закройте его с сообщением, указывающим на даты исправлений в каждой ветке.

  • Если PR описывает ошибку, которая, по вашим данным, была исправлена в -CURRENT, но не в -STABLE, попытайтесь выяснить, когда человек, исправивший эту ошибку, планирует выполнить MFC, либо попробуйте найти для этого кого-то ещё (может, это будете вы сами?). Измените состояние сообщения на ''patched'' и переназначьте его кому-либо, кто будет делать MFC.

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


4.5. Незаполненные PR

GNATS требовательно подходит к формату присылаемых сообщений об ошибках. Вот почему много PR заканчивают жизнь в состоянии ''misfiled'', если посылающий забыл заполнить поле или ввёл неправильные данные в некоторые поля PR. Этот раздел поможет предоставить основной объём необходимых подробностей для разработчиков FreeBSD, который может помочь им закрыть или повторно заполнить эти PR.

Если система GNATS не может понять, что делать с сообщением об ошибке, которое достигло базы данных, она определяет gnats-admin в качестве ответственного за PR и помещает сообщение в категорию pending. Теперь это PR в состоянии ''misfiled'' и оно не будет появляться в списках сообщений об ошибках, если только кто-то специально не запросит перечень всех незаполненных PR. Если у вас есть доступ к машинам в кластере FreeBSD, можете воспользоваться командой query-pr для просмотра списка PR, которые были некорректно сформированы:

% query-pr -x -q -r gnats-admin
   52458 gnats-ad   open      serious   medium    Re: declaration clash f
   52510 gnats-ad   open      serious   medium    Re: lots of sockets in
   52557 gnats-ad   open      serious   medium
   52570 gnats-ad   open      serious   medium    Jigdo maintainer update

Как правило, PR вроде перечисленных выше оказываются незаполненными по одной из следующих причин:

  • Отклик на существующее PR, посланный по электронной почте, имеет неверный формат заголовка Subject:.

  • Автор PR отправил копию (Cc:) в список рассылки, а кто-нибудь ответил на этот пост вместо сообщения, сформированного GNATS. В копии, отосланной в список рассылки, нету тега категория/PRномер. (Вот почему мы рекомендуем посылающим не делать подобных движений).

  • При заполнении шаблона send-pr(1) посылающий забыл указать правильное значение для категории или класса PR.

  • При заполнении шаблона send-pr(1) посылающий установил значение поля Confidential в yes. (Так как мы позволяем каждому зеркалировать GNATS при помощи cvsup, информация о PR-ах является общедоступной. Сообщения, касающиеся безопасности, не следует слать через GNATS, их необходимо отправлять на адрес команды офицеров безопасности).

  • Это не реальное PR, а какое-то случайное сообщение, посланное на адрес или .


4.5.1. Отклики неправильно оформлены как новые PR

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

Subject: Re: category/number: старая тема

Большинство почтовых программ, когда вы отвечаете на оригинальное почтовое сообщение с PR, будут добавлять часть ''Re: ''. Часть ''category/number: '' является соглашением, специфичным для GNATS, которое вы должны выполнить, вручную поставив его в тему письма с откликом.

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

Your problem report was misfiled.  Please use the format
"Subject: category/number: original text" when following
up to older, existing PRs.  I've added the relevant bits
from the body of this PR to kern/12345

Поиск по команде query-pr оригинального PR, на которое отвечает неправильно оформленный отклик, легко выполняется следующим образом:

% query-pr -q -y "some text"

После того, как вы обнаружили оригинальное PR и неправильно оформленный отклик на него, воспользуйтесь параметром -F команды query-pr для сохранения полного текста всех относящихся к делу PR в файле формата почтового ящика UNIX®, то есть:

% query-pr -F 52458 52474 > mbox

Теперь вы можете использовать любую почтовую программу для просмотра всех PR, которые вы сохранили в файле mbox. Скопируйте текст всех неверно оформленных PR в отклике на оригинальное сообщение о проблеме, и обязательно включите правильный заголовок Subject:. После этого закройте неверно оформленное PR. Когда вы закрываете такие PR, помните, что автор получает оповещение по почте о том, что его PR сменило состояние на ''closed''. В пояснении обязательно описывайте в подробностях, почему это состояние изменилось. Обычно подойдёт примерно следующий текст:

Followup to ports/45364 misfiled as a new PR.
This was misfiled because the subject did not have the format:

	Re: ports/45364: ...

В этом случае автор неправильно оформленного PR будет знать, чего необходимо избегать при отправке отклика на существующее PR.


4.5.2. Некорректные PR с отсутствующими полями

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

Отсутствие или ошибочное задание полей ''category'' или ''class'' может привести к появлению некорректного сообщения. Разработчики могут использовать edit-pr(1) для смены значений категории или класса этих неправильно оформленных PR на более подходящие и сохранить PR.

Другой распространённой причиной появления неправильно оформленных PR являются вопросы форматирования, квотирование, изменение или удаление шаблона send-pr, как по вине пользователя, редактирующего шаблон, так и почтовых программ, которые проделывают странные вещи с обычными текстовыми сообщениями. Это изредка случается и может быть исправлено программой edit-pr, что требует некоторых усилий со стороны разработчика, корректирующего PR, однако в большинстве случаев это можно сделать относительно легко.


4.5.3. Неправильные PR, которые на самом деле не являются сообщениями об ошибках

Иногда пользователь желает сообщить об ошибке и посылает GNATS по электронной почте обычное сообщение. Скрипты GNATS работает с сообщениями об ошибках, которые форматированы при помощи шаблона send-pr(1). Они не могут обрабатывать любые сообщения электронной почты. Вот почему сообщения об ошибках, посылаемые на адрес , должны быть оформлены по шаблону команды send-pr, хотя сообщения по электронной почте можно послать на Список рассылки FreeBSD, посвящённый сообщениям о проблемах.

Разработчики, которые видят PR, выглядящие так, будто они должны были быть посланы в адрес freebsd-bugs или какого-то другого списка рассылки, должны закрыть PR, проинформировав его автора в протоколе изменения состояния о причинах, по которых это не является настоящим PR и куда следует посылать сообщения.

Электронный адрес, который использует GNATS для приёма поступающих PR, опубликован в документации к FreeBSD, объявлялся и указан на Web-сайте. Это значит, что спамеры его увидели. Спам-сообщения, достигшие GNATS, немедленно определяются в категорию ''pending'' и остаются там до тех пор, пока кто-нибудь их не пересмотрит. Закрытие любого из таких сообщений при помощи edit-pr(1) весьма раздражает, потому что GNATS отвечает автору, а адрес отправителя спам-почты никогда не бывает настоящим. Для каждого закрытого PR будут приходить сообщения о невозможности доставки.

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

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

  • Выставьте Category в junk.

  • Установите Confidential в no.

  • Установите Responsible в gnats-admin.

  • Смените State в closed.

Для PR категории junk не выполняется резервное копирование, следовательно, перевод спам сообщений в эту категорию обозначает, что мы не желаем хранить их или тратить дисковое пространство на них. Если вы просто закрываете их без смены категории, они остаются как в главной базе, так и во всех копиях базы, зеркалируемых через cvsup.


5. Дополнительная литература

Это перечень ресурсов, относящихся к качественному написанию и обработке сообщений об ошибках. Несомненно, этот список не является полным.


Этот, и другие документы, могут быть скачаны с ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/.

По вопросам, связанным с FreeBSD, прочитайте документацию прежде чем писать в <questions@FreeBSD.org>.
По вопросам, связанным с этой документацией, пишите <doc@FreeBSD.org>.
По вопросам, связанным с русским переводом документации, пишите в рассылку <frdp@FreeBSD.org.ua>.
Информация по подписке на эту рассылку находится на сайте проекта перевода.