os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Initial import, synchronized with English 1.14

Browse source
This commit is contained in:
Andrey Zakhvatov 2004-02-21 15:33:56 +00:00
parent 31357b0446
commit 6185c87a6f
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=20123
1 changed files with 557 additions and 0 deletions

557
ru_RU.KOI8-R/articles/pr-guidelines/article.sgml Normal file
View file

@ -0,0 +1,557 @@
<!--
The FreeBSD Russian Documentation Project
$FreeBSDru: frdp/doc/ru_RU.KOI8-R/articles/pr-guidelines/article.sgml,v 1.1 2004/02/06 16:59:32 andy Exp $
Original revision: 1.14
-->
<!--
Problem Report Handling Guidelines
The FreeBSD Project - http://www.FreeBSD.org
-->
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
%man;
<!ENTITY % mailing-lists PUBLIC "-//FreeBSD//ENTITIES DocBook Mailing List Entities//RU">
%mailing-lists;
<!ENTITY % freebsd PUBLIC "-//FreeBSD//ENTITIES DocBook Miscellaneous FreeBSD Entities//EN">
%freebsd;
<!ENTITY % trademarks PUBLIC "-//FreeBSD//ENTITIES DocBook Trademark Entities//EN">
%trademarks;
<!ENTITY man.edit-pr.1 "<citerefentry/<refentrytitle/edit-pr/<manvolnum/1//">
<!ENTITY man.query-pr.1 "<citerefentry/<refentrytitle/query-pr/<manvolnum/1//">
]>
<article>
<!-- :START of Article Metadata -->
<articleinfo>
<title>Рекомендации по работе с сообщениями о проблемах</title>
<pubdate>$FreeBSD$</pubdate>
<legalnotice id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.opengroup;
&tm-attrib.general;
</legalnotice>
<abstract>
<para>Это руководство описывает рекомендуемую практику обработки
сообщений об ошибках FreeBSD (Problem Reports - PR). Хотя эти
рекомендации предназначены для Группы поддержки базы данных сообщений
о проблемах FreeBSD (PR Database Maintenance Team)
<email>freebsd-bugbusters@FreeBSD.org</email>, им должны следовать все,
кто работает с этими сообщениями.</para>
</abstract>
<authorgroup>
<author>
<firstname>Dag-Erling</firstname>
<surname>Sm&oslash;rgrav</surname>
</author>
<author>
<firstname>Hiten</firstname>
<surname>Pandya</surname>
</author>
</authorgroup>
</articleinfo>
<!-- :END of Article Metadata-->
<section id="intro">
<title>Введение</title>
<para>GNATS является системой управления неисправностями (сообщениями об
ошибках), которая используется в Проекте FreeBSD. Так как тщательное
отслеживание заметных изъянов в программном обеспечении важно для
обеспечения качества FreeBSD, правильное использование GNATS необходимо
для дальнейшего развития Проекта.</para>
<para>Доступ к GNATS даётся разработчикам FreeBSD, а также более широкому
сообществу. Для того, чтобы поддерживать целостность базы данных и
единства работы с пользователями, выработанные рекомендации покрывают
общие вопросы управления проблемами, такие, как написание отклика,
обработку уже закрытых вопросов и так далее.</para>
</section>
<section id="pr-lifecycle">
<title>Жизненный цикл сообщения об ошибке</title>
<itemizedlist>
<listitem>
<para>Респондент посылает PR при помощи утилиты &man.send-pr.1; и
получает подтверждающее сообщение.</para>
</listitem>
<listitem>
<para>Среднестатический коммиттер (Вася) проявляет интерес к PR и
назначает его самому себе, или другой любитель ошибок (Петя) решает,
что лучше всех с описанной проблемой справится именно Вася, и
назначает её Васе.</para>
</listitem>
<listitem>
<para>Вася связывается с Респондентом (при этом вся переписка должна
фиксироваться) и выясняет причину появления проблемы. Затем он
документирует причину в журнале аудита, и переводит PR в состояние
<quote>analyzed</quote> (проанализировано).</para>
</listitem>
<listitem>
<para>Вася проводит бессонную ночь и выпускает патч, которая, по его
мнению, решает означенную проблему, и затем посылает её ответом,
прося Респондента протестировать его. Затем он переводит PR в
состояние <quote>feedback</quote>.</para>
</listitem>
<listitem>
<para>Через несколько таких итераций Вася и Респондент удавлетворяются
получающимся патчем, и Вася переносит его в дерево
<literal>-CURRENT</literal> (или непосредственно в
<literal>-STABLE</literal>, если этой проблемы в
<literal>-CURRENT</literal> не наблюдается), при этом при выполнении
коммита в сопутствующем сообщении делается ссылка на сообщение о
проблеме (а также упоминается Респондент, если он последний весь или
часть патча), и, если это нужно, начинается отсчёт для MFC.</para>
</listitem>
<listitem>
<para>Если патчу не нужно выполнение MFC, Вася закрывает PR.</para>
</listitem>
<listitem>
<para>Если патч требует выполнения MFC, Вася оставляет Сообщение о
проблеме в состоянии <quote>patched</quote> до выполнения операции
MFC, а затем закрывает его.</para>
</listitem>
</itemizedlist>
<note>
<para>Многие PR присылаются с очень слабым описанием проблемы, а
некоторые из них либо очень сложно решить, либо являются вершиной
айсберга другой, более широкой проблемы; в этих случаях очень важно
получить всю информацию, требуемую для решения проблемы. Если
описанная проблема не может быть решена, или проявится снова,
необходимо повторно открыть PR.</para>
</note>
<note>
<para>Адрес <quote>электронной почты</quote> может оказаться недоступным.
В этом случае ответьте на PR обычным образом и попросите Респондента
(в своём сообщении) предоставить рабочий адрес электронной почты.
Обычно это происходит в случаях использования &man.send-pr.1; в
системах с выключенной или неустановленной почтовой системой.</para>
</note>
</section>
<section id="pr-states">
<title>Состояние сообщений о проблемах</title>
<para>При выполнении некоторых действий очень важно обновлять состояние
PR. Это состояние должно в точности отражать текущее состояние работы
над PR.</para>
<example>
<title>Маленький пример того, когда именно нужно менять
состояние PR</title>
<para>Когда PR находится в работе и ответственный разработчик(и)
удовлетворён получающимся решением, то он отвечает на PR и меняет его
состояние на <quote>feedback</quote>. В этот момент Респондент должен
изучить исправление в своей ситуации и ответить, действительно ли был
устранён дефект.</para>
</example>
<para>Сообщение о проблеме может находится в одном из следующих
состояний:</para>
<glosslist>
<glossentry>
<glossterm>open</glossterm>
<glossdef>
<para>Начальное состояние; проблема была поставлена и её необходимо
рассмотреть.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>analyzed</glossterm>
<glossdef>
<para>Проблема была рассмотрена, ищется её решение.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>feedback</glossterm>
<glossdef>
<para>Дальнейшая работа требует дополнительной информации от
Респондента или сообщества; возможно помещение информации о
предлагаемом решении.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>patched</glossterm>
<glossdef>
<para>Патч был перенесён в дерево исходных текстов, но
что-то (выполнение MFC или, возможно, подтверждение Респондента)
ещё требуется доделать.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>suspended</glossterm>
<glossdef>
<para>Работа над проблемой была остановлена из-за отсутствия
информации или необходимых ресурсов. Это первый кандидат для
тех, кто ищет проект для работы над ним. Если проблема вообще не
может быть решена, она будет закрыта, а не приостановлена. Проект
создания документации использует <quote>suspended</quote> для
<quote>желательных</quote> нововведений, которые требуют
значительной работы, для которой ни у кого пока нет времени.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>closed</glossterm>
<glossdef>
<para>Сообщение о проблеме было закрыто, когда все изменения были
перенесены, задокументированы и протестированы, либо когда
исправление проблемы было отвергнуто.</para>
</glossdef>
</glossentry>
</glosslist>
<note>
<para>Состояние <quote>patched</quote> напрямую связано с предлагаемыми
решениями, так что вы можете перейти сразу к состоянию
<quote>closed</quote>, если Респондент не может простестировать патч,
либо на ваших тестовых прогонах он работает.</para>
</note>
</section>
<section id="pr-types">
<title>Типы сообщений о проблемах</title>
<para>При обработке сообщений об ошибках, либо в качестве разработчика,
имеющего непосредственный доступ к базе данных GNATS, либо в качестве
контрибутора, который просматривает базу данных и посылает свои
отклики с патчами, комментариями, пожеланиями или запросами на изменение,
вы будете иметь дело с несколькими различными типами PR.</para>
<itemizedlist>
<listitem>
<para><link linkend="pr-assigned">PR, которые уже кому-то
назначены.</link></para>
</listitem>
<listitem>
<para><link linkend="pr-dups">Повторы существующих PR.</link></para>
</listitem>
<listitem>
<para><link linkend="pr-stale">Заброшенные PR</link></para>
</listitem>
<listitem>
<para><link linkend="pr-misfiled">Некорректные PR</link></para>
</listitem>
</itemizedlist>
<para>В последующих разделах описывается, для чего предназначены те или
иные типы PR, условия отнесения PR к одному из этих типов, и какое
внимание нужно уделять каждому из этих типов.</para>
<section id="pr-assigned">
<title>Назначение PR</title>
<para>Если в PR в заполненном поле <literal>responsible</literal> указано
имя разработчика FreeBSD, это значит, что PR взята этим человеком для
дальнейшей работы.</para>
<para>Уже назначенное PR не должно трогаться никем, кроме того, кому эта
проблема назначена. Если у вас есть комментарии, напишите отклик.
Если по какой-то причине вы думаете, что PR должна изменить своё
состояние или её необходимо назначить кому-то другому, пошлите
сообщение тому, кто назначен ответственным. Если этот человек не
ответит в течение двух недель, смените назначение PR, а дальше
действуйте по своему усмотрению.</para>
</section>
<section id="pr-dups">
<title>Повторные PR</title>
<para>Если вы обнаружите, что один и тот же вопрос описывается более чем
в одном PR, выберите то, что содержит максимальный объём полезной
информации и закройте все остальные, чётко указав номер более полного
PR. Если несколько PR содержат непересекающуюся информацию, перенесите
всю недостающую информацию в какой-либо отклик, включая ссылки на
остальные PR; затем закройте другие PR (которые теперь полностью
перекрыты).</para>
</section>
<section id="pr-stale">
<title>Просроченные PR</title>
<para>PR считается простроченным, если оно не модифицировалось в течение
более полугода. При обработке просроченных PR испольщуйте следующую
процедуру:</para>
<itemizedlist>
<listitem>
<para>Если PR достаточно подробна, попытайтесь воспроизвести проблему
в дереве <literal>-CURRENT</literal> и <literal>-STABLE</literal>.
Если вам это удалось, напишите отклик, описывающий ваши изыскания
и попытайтесь найти кого-то, кому эту проблему можно назначить.
Если это подходит, измените состояние
на <quote>analyzed</quote>.</para>
</listitem>
<listitem>
<para>Если PR описывает проблему, которая, как вы знаете, является
результатом неправильного использования (некорректная настройка или
что-то ещё), напишите отклик, в котором опишите, что автор
исходного сделал не так, а затем закройте PR с описанием
<quote>User error</quote> или <quote>Configuration
error</quote>.</para>
</listitem>
<listitem>
<para>Если в PR описывается ошибка, которая, как вы знаете, была
исправлена как в <literal>-CURRENT</literal>, так и
<literal>-STABLE</literal>, закройте его с сообшением, указывающим
на даты исправлений в каждой ветке.</para>
</listitem>
<listitem>
<para>Если PR описывает ошибку, которая, по вашим данным, была
исправлена в <literal>-CURRENT</literal>, но не в
<literal>-STABLE</literal>, попытайтесь выяснить, когда человек,
исправивший эту ошибку, планирует выполнить MFC, либо попробуйте
найти для этого кого-то ещё (может, это будете вы сами?). Измените
состояние сообщения на <quote>feedback</quote> и переназначьте его
кому-либо, кто будет делать MFC.</para>
</listitem>
<listitem>
<para>В остальных случаях запросите у автора исходного сообщения
подтверждения того, что проблема всё ещё присутствует в новых
версиях. Если автор не отвечает в течение месяца, закройте PR с
пометкой <quote>Feedback timeout</quote>.</para>
</listitem>
</itemizedlist>
</section>
<section id="pr-misfiled">
<title>Незаполненные PR</title>
<para>GNATS требовательно подходит к формату присылаемых сообщений об
ошибках. Вот почему много PR заканчивают жизнь в состоянии
<quote>misfiled</quote>, если посылающий забыл заполнить поле или
ввёл неправильные данные в некоторые поля PR. Этот раздел поможет
предоставить основной объём необходимых подробностей для разработчиков
FreeBSD, который может помочь им закрыть или повторно заполнить
эти PR.</para>
<para>Если система GNATS не может понять, что делать с сообщением об
ошибке, которое достигло базы данных, она определяет
<literal>gnats-admin</literal> в качестве ответственного за PR и
помещает сообщение в категорию <literal>pending</literal>. Теперь это
PR в состоянии <quote>misfiled</quote> и оно не будет появляться в
списках сообщений об ошибках, если только кто-то специально не запросит
перечень всех незаполненных PR. Если у вас есть доступ к машинам в
кластере FreeBSD, можете воспользоваться командой
<command>query-pr</command> для просмотра списка PR, которые были
некорректно сформированы:</para>
<screen>&prompt.user; <userinput>query-pr -x -q -r gnats-admin</userinput>
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</screen>
<para>Как правило, PR вроде перечисленных выше оказываются незаполненными
по одной из следующих причин:</para>
<itemizedlist>
<listitem>
<para>Отклик на существующее PR, посланный по электронной почте,
имеет неверный формат заголовка <literal>Subject:</literal>.</para>
</listitem>
<listitem>
<para>При заполнении шаблона &man.send-pr.1; посылающий забыл указать
правильное значение для категории или класса PR.</para>
</listitem>
<listitem>
<para>Это не реальное PR, а какое-то случайное сообщение, посланное
на адрес <email>bug-followup@freebsd.org</email> или
<email>freebsd-gnats-submit@freebsd.org</email>.</para>
</listitem>
</itemizedlist>
<section id="pr-misfiled-followups">
<title>Отклики неправильно оформлены как новые PR</title>
<para>К наиболее массовой категории неправильно оформленных PR
относятся те, у которых неверна тема письма, и именно они на самом
деле требует самых больших усилий от разработчиков. Это не настоящие
PR, описывающие отдельные ошибки. Когда по одному из адресов,
который <quote>прослушивает</quote> GNATS на предмет обработки
входящих сообщений, принимается ответ на существуещее PR, то тема
ответа должна быть всегда в таком виде:</para>
<programlisting>Subject: Re: category/number: старая тема</programlisting>
<para>Большинство почтовых программ, когда вы отвечаете на оригинальное
почтовое сообщение с PR, будут добавлять часть
<quote><literal>Re:&nbsp;</literal></quote>. Часть
<quote><literal>category/number:&nbsp;</literal></quote> является
соглашением, специфичным для GNATS, которое вы должны выполнить,
вручную поставив его в тему письма с откликом.</para>
<para>Все разработчики FreeBSD, имеющие прямой доступ к базе данных
GNATS, могут регулярно проверять наличие таких PR и перемещать
заинтересовавшие их в отклики к оригинальному PR (послав корректный
отклик на сообщение об ошиюке на адрес
<email>bug-followup@freebsd.org</email>). Затем неправильно
оформленное PR может быть закрыто с примерно таким пояснением:</para>
<programlisting>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</programlisting>
<para>Поиск по команде <command>query-pr</command> оригинального PR,
на которое отвечает неправильно оформленный отклик, легко выполняется
следующим образом:</para>
<screen>&prompt.user; query-pr -q -y "some text"</screen>
<para>После того, как вы обнаружили оригинальное PR и неправильно
оформленный отклик на него, воспользуйтесь параметром
<option>-F</option> команды <command>query-pr</command> для
сохранения полного текста всех относящихся к делу PR в файле формата
почтового ящика &unix;, то есть:</para>
<screen>&prompt.user; <userinput>query-pr -F 52458 52474 &gt; mbox</userinput></screen>
<para>Теперь вы можете использовать любую почтовую программу для
просмотра всех PR, которые вы сохранили в файле
<filename>mbox</filename>. Скопируйте текст всех неверно оформленных
PR в отклике на оригинальное сообщение о проблеме, и обязательно
включите правильный заголовок <literal>Subject:</literal>. После
этого закройте неверно оформленное PR. Когда вы закрываете такие PR,
помните, что автор получает оповещение по почте о том, что его PR
сменило состояние на <quote>closed</quote>. В пояснении обязательно
описывайте в подробностях, почему это состояние изменилось. Обычно
подойдёт примерно следующий текст:</para>
<programlisting>Followup to ports/45364 misfiled as a new PR.
This was misfiled because the subject didn't have the format:
Re: ports/45364: ...</programlisting>
<para>В этом случае автор неправильно оформленного PR будет знать,
чего необходимо избегать при отправке отклика на существующее
PR.</para>
</section>
<section id="pr-misfiled-format">
<title>Некорректные PR с отсутствующими полями</title>
<para>Ко второму типу неправильно оформленных PR обычно относят те,
что являются результатом забывчивости авторов, которые не заполнили
все необходимые поля при написании первоначального PR.</para>
<para>Отсутствие или ошибочное задание полей <quote>category</quote>
или <quote>class</quote> может привести к появлению некорректного
сообщения. Разработчики могут использовать &man.edit-pr.1; для смены
значений категории или класса этих неправильно оформленных PR на
более подходящие и сохранить PR.</para>
<para>Другой распространённой причиной появления неправильно
оформленных PR являются вопросы форматирования, квотирование,
изменение или удаление шаблона <command>send-pr</command>, как по
вине пользователя, редактирующего шаблон, так и почтовых программ,
которые проделывают странные вещи с обычными текстовыми сообщениями.
Это происходит не постоянно, и может быть исправлено программой
<command>edit-pr</command>; это требует некоторых усилий со стороны
разработчика, которые перевводит PR, однако в большинстве случаев
это можно сделать относительно легко.</para>
</section>
<section id="pr-misfiled-notpr">
<title>Неправильные PR, которые на самом деле не являются сообщениями
об ошибках</title>
<para>Иногда пользователь желает сообщить об ошибке и посылает GNATS
по электронной почте обычное сообщение. Скрипты GNATS работает с
сообщениями об ошибках, которые форматированы при помощи шаблона
&man.send-pr.1;. Они не могут обрабатывать любые сообщения
электронной почты. Вот почему сообщения об ошибках, посылаемые на
адрес <email>freebsd-gnats-submit@freebsd.org</email>, должны
быть оформлены по шаблону команды <command>send-pr</command>, хотя
сообщения по электронной почте можно послать на &a.bugs;.</para>
<para>Разработчики, которые видят PR, выглядящие так, будто они должны
были быть посланы в адрес &a.bugs.name; или какого-то другого
списка рассылки, должны закрыть PR, проинформировав его автора в
протоколе изменения состояния о причинах, по которых это не является
настоящим PR и куда следует посылать сообщения.</para>
<para>Электронный адрес, который использует GNATS для приёма
поступающих PR, опубликован в документации к FreeBSD, объявлялся и
указан на Web-сайте. Это значит, что спамеры его увидели. Каждый
день несколько рекламных сообщений поступает в GNATS, которая
относит их к категории <quote>pending</quote>, пока кто-нибудь их не
пересмотрит. Закрытие любого из таких сообщений при помощи
&man.edit-pr.1; весьма раздражает, потому что GNATS отвечает автору,
а сейчас адрес отправителя спам-почты никогда не бывает настоящим.
Для каждого закрытого PR будут приходить сообщения о
невозможности доставки.</para>
<para>На данный момент с установкой некоторых фильтров против спама,
проверяющих все добавления в базу данных GNATS, количество спама,
достигающего состояния <quote>pending</quote>, весьма мало.</para>
<para>Все разработчики, имеющие доступ к машинам кластера FreeBSD.org,
приглашаются к проверке неправильно оформленных PR и немедленному
закрытию тех, что являются почтовым спамом. Когда вы закрываете
такое PR, хорошо бы заодно указать в качестве категории
<quote><literal>junk</literal></quote>. Ненужные PR не сохраняются,
так что перенос почтового спама в эту категорию ясно указывает на
то, что мы не собираемся его сохранять или тратить на него дисковое
пространство.</para>
</section>
</section>
</section>
<section id="references">
<title>Дополнительная литература</title>
<para>Это перечень ресурсов, относящихся к качественному написанию и
обработке сообщений об ошибках. Несомненно, этот список не является
полным.</para>
<itemizedlist>
<listitem>
<para><ulink
url="../../articles/problem-reports/article.html">Как писать
Сообщения об ошибках FreeBSD</ulink>&mdash;руководство для авторов
PR.</para>
</listitem>
</itemizedlist>
</section>
</article>