507ebf0702
- Generated by chinsan, psilotum, tzhuan, whsyu PR: ports/99074 Submitted by: chinsan <chinsan.tw@gmail.dot.com>
881 lines
29 KiB
Text
881 lines
29 KiB
Text
<!-- $FreeBSD$ -->
|
||
<!-- The FreeBSD Documentation Project -->
|
||
<!-- Translate into Chinese by chinsan.tw@gmail.com -->
|
||
<!-- English Version: 1.24 -->
|
||
<!--
|
||
問題回報(PR)的處理原則
|
||
The FreeBSD Project - http://www.FreeBSD.org
|
||
-->
|
||
|
||
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
|
||
<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN">
|
||
%articles.ent;
|
||
<!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>問題回報(PR)的處理原則</title>
|
||
|
||
<pubdate>$FreeBSD$</pubdate>
|
||
|
||
<legalnotice id="trademarks" role="trademarks">
|
||
&tm-attrib.freebsd;
|
||
&tm-attrib.opengroup;
|
||
&tm-attrib.general;
|
||
</legalnotice>
|
||
|
||
<abstract>
|
||
<para>這篇文章主要在講：由 FreeBSD PR 維護小組所提出的一些 FreeBSD 問題回報(PR)
|
||
建議，希望大家在弄 PR 時都能遵守。</para>
|
||
</abstract>
|
||
|
||
<authorgroup>
|
||
<author>
|
||
<firstname>Dag-Erling</firstname>
|
||
<surname>Smø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 計劃所採用的一套專門管理錯誤(回報bug) 系統。
|
||
由於對 FreeBSD 品質保證而言，是否能準確掌握各項錯誤回報與進度是十分重要的，
|
||
因此，如何正確有效使用 GNATS 也就必須注意。</para>
|
||
|
||
<para>Access to GNATS is available to FreeBSD developers, as well as
|
||
to the wider community. 為了讓 GNATS 資料庫使用上儘量一致，於是就產生了怎麼處理像是：followup(回文)、關閉PR等的參考原則。</para>
|
||
</section>
|
||
|
||
<section id="pr-lifecycle">
|
||
<title>問題回報(PR)的生命週期</title>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>首先，回報者(originator)以 &man.send-pr.1; 送出 PR，然後會收到一封確認信。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>然後，committer 們就會有人(假設叫做 Joe)發掘有興趣的 PR 並將該 PR 指派給自己來處理。
|
||
或者 bugbuster 會有人(假設叫做 Jane) 就會下決定：她覺得 Joe 比較適合處理，就將該 PR 指派(assign)給他</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>Joe 會先與有問題的回報者作些意見交流(以確定這問題有進入 audit 追蹤流程內)
|
||
以及判斷問題點。
|
||
然後再確定問題點有寫入 audit 追蹤流程之後，然後把該 PR 狀態設為
|
||
<quote>analyzed(已分析)</quote>。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>Joe 開始徹夜找出問題解法，然後將 patch 送到 follow-up(回文用)，並請回報者協助測試是否正常。
|
||
然後，他就會將 PR 狀態設為 <quote>feedback</quote> 囉。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>如此重複 analyzed、feedback 幾趟之後，直到 Joe 與回報者雙方都相當滿意 patch 結果，
|
||
於是就會將 patch 給 commits 進入 <literal>-CURRENT</literal> (或者若 <literal>-CURRENT</literal>
|
||
上面沒這問題的話，就直接送到 <literal>-STABLE</literal>)，在 commit log 內要把相關 PR 寫上去
|
||
(同時回報者若有送完整或部分 patch 的話，就順便記載)，然後，若沒什麼事的話，就開始準備 MFC 哩。
|
||
(譯註：MFC意指 Merged From CURRENT ，也就是把 <literal>-CURRENT</literal> 上的東西併入 <literal>-STABLE</literal>。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>若該 patch 不需要 MFC 的話，Joe 就會關掉(close)該 PR 了。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>若該 patch 需要 MFC 的話，Joe 會把 PR 狀態改為 <quote>patched(已修正)</quote>，
|
||
直到已經 MFC 完畢，才會 close(關掉)。</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<note>
|
||
<para>很多送出來的 PR 都很少附上問題的相關訊息，而有些則是相當複雜難搞，
|
||
或只是提到部分表面問題而已；
|
||
遇到這種情況時，是非常需要得到所有相關訊息以便解決問題。
|
||
若遇到這種無解的問題或再次發生的話，就必須要 re-open(重新開啟) 該 PR，以待解決。</para>
|
||
</note>
|
||
<note>
|
||
<para>PR 上所附的 <quote>email address</quote> 可能因某些原因而無法收信時，遇到這種狀況，通常就是
|
||
followup 該 PR ，並(在 followup 時)請回報者重新提供可正常收信的 email address。
|
||
當系統上的 mail 系統關閉或沒裝的時候，這通常是在使用 &man.send-pr.1; 的替代方案。</para>
|
||
</note>
|
||
</section>
|
||
|
||
<section id="pr-states">
|
||
<title>問題回報(PR)的狀態</title>
|
||
|
||
<para>若 PR 有任何變化的話，請務必記得更新 PR 的『狀態(state)』。
|
||
『狀態』應該要能正確反映該 PR 的目前進度才是。</para>
|
||
|
||
<example>
|
||
<title>以下是更改 PR 狀態的小例子：</title>
|
||
|
||
<para>當有可以修正問題的 PR 出現，而相關負責的 developer(s)
|
||
也覺得這樣的修正可以接受，他們會 followup 該 PR，並將其狀態改為
|
||
<quote>feedback</quote>。同時，回報者應重新評估最終的修正結果，並回應：所回報的錯誤是否已成功修正。</para>
|
||
</example>
|
||
|
||
<para>每份 PR 通常會有下面這幾種狀態之一：</para>
|
||
|
||
<glosslist>
|
||
<glossentry>
|
||
<glossterm>open</glossterm>
|
||
<glossdef>
|
||
<para>PR 最初的狀態：這個問題被提出來，並在等待處理中。</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>已經送相關 patch 了，但仍因某些原因(MFC，或來自回報者的確認結果異常)因此尚未完畢。</para>
|
||
</glossdef>
|
||
</glossentry>
|
||
|
||
<glossentry>
|
||
<glossterm>suspended(暫緩)</glossterm>
|
||
<glossdef>
|
||
<para>因為沒附上相關訊息或參考資料，所以還沒辦法處理這問題。
|
||
This is a prime candidate for
|
||
somebody who is looking for a project to take on. If the
|
||
problem cannot be solved at all, it will be closed, rather
|
||
than suspended. The documentation project uses
|
||
<quote>suspended</quote> for <quote>wish-list</quote>
|
||
items that entail a significant amount of work which no one
|
||
currently has time for.</para>
|
||
</glossdef>
|
||
</glossentry>
|
||
|
||
<glossentry>
|
||
<glossterm>closed</glossterm>
|
||
<glossdef>
|
||
<para>A problem report is closed when any changes have been
|
||
integrated, documented, and tested, or when fixing the
|
||
problem is abandoned.</para>
|
||
</glossdef>
|
||
</glossentry>
|
||
</glosslist>
|
||
|
||
<note>
|
||
<para>The <quote>patched</quote> state is directly related to
|
||
feedback, so you may go directly to <quote>closed</quote> state if
|
||
the originator cannot test the patch, and it works in your own testing.</para>
|
||
</note>
|
||
</section>
|
||
|
||
<section id="pr-types">
|
||
<title>問題回報(PR)的種類</title>
|
||
|
||
<para>While handling problem reports, either as a developer who has
|
||
direct access to the GNATS database or as a contributor who
|
||
browses the database and submits followups with patches, comments,
|
||
suggestions or change requests, you will come across several
|
||
different types of PRs.</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para><link linkend="pr-unassigned">PRs not yet assigned to anyone.</link></para>
|
||
</listitem>
|
||
<listitem>
|
||
<para><link linkend="pr-assigned">PRs already assigned to someone.</link></para>
|
||
</listitem>
|
||
<listitem>
|
||
<para><link linkend="pr-dups">重複的 PR</link></para>
|
||
</listitem>
|
||
<listitem>
|
||
<para><link linkend="pr-stale">Stale PRs</link></para>
|
||
</listitem>
|
||
<listitem>
|
||
<para><link linkend="pr-misfiled">Misfiled PRs</link></para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<para>The following sections describe what each different type of
|
||
PRs is used for, when a PR belongs to one of these types, and what
|
||
treatment each different type receives.</para>
|
||
|
||
<section id="pr-unassigned">
|
||
<title>Unassigned PRs</title>
|
||
|
||
<para>When PRs arrive, they are initially assigned to a generic
|
||
(placeholder) assignee. These are always prepended with
|
||
<literal>freebsd-</literal>. The exact value for this default
|
||
depends on the category; in most cases, it corresponds to a
|
||
specific &os; mailing list. Here is the current list, with
|
||
the most common ones listed first:</para>
|
||
|
||
<table id=default-assignees-common>
|
||
<title>Default Assignees — most common</title>
|
||
<tgroup cols="3">
|
||
<thead>
|
||
<row>
|
||
<entry>Type</entry>
|
||
<entry>Categories</entry>
|
||
<entry>Default Assignee</entry>
|
||
</row>
|
||
</thead>
|
||
|
||
<tbody>
|
||
<row>
|
||
<entry>base system</entry>
|
||
<entry>bin, conf, gnu, kern, misc</entry>
|
||
<entry>freebsd-bugs</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>architecture-specific</entry>
|
||
<entry>alpha, i386, ia64, powerpc, sparc64</entry>
|
||
<entry>freebsd-<replaceable>arch</replaceable></entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>ports collection</entry>
|
||
<entry>ports</entry>
|
||
<entry>freebsd-ports-bugs</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>documentation shipped with the system</entry>
|
||
<entry>docs</entry>
|
||
<entry>freebsd-doc</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>&os; web pages (not including docs)</entry>
|
||
<entry>www</entry>
|
||
<entry>freebsd-www</entry>
|
||
</row>
|
||
</tbody>
|
||
</table>
|
||
|
||
<table id=default-assignees-other>
|
||
<title>Default Assignees — other</title>
|
||
<tgroup cols="3">
|
||
<thead>
|
||
<row>
|
||
<entry>Type</entry>
|
||
<entry>Categories</entry>
|
||
<entry>Default Assignee</entry>
|
||
</row>
|
||
</thead>
|
||
|
||
<tbody>
|
||
<row>
|
||
<entry>advocacy efforts</entry>
|
||
<entry>advocacy</entry>
|
||
<entry>freebsd-advocacy</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>&java.virtual.machine; problems</entry>
|
||
<entry>java</entry>
|
||
<entry>freebsd-java</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>standards compliance</entry>
|
||
<entry>standards</entry>
|
||
<entry>freebsd-standards</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>threading libraries</entry>
|
||
<entry>threads</entry>
|
||
<entry>freebsd-threads</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>&man.usb.4; subsystem</entry>
|
||
<entry>usb</entry>
|
||
<entry>freebsd-usb</entry>
|
||
</row>
|
||
</tbody>
|
||
</table>
|
||
|
||
<para>Do not be surprised to find that the submitter of the
|
||
PR has assigned it to the wrong category. If you fix the
|
||
category, do not forget to fix the assignment as well.
|
||
(In particular, our submitters seem to have a hard time
|
||
understanding that just because their problem manifested
|
||
on an i386 system, that it might be generic to all of &os;,
|
||
and thus be more appropriate for <literal>kern</literal>.
|
||
The converse is also true, of course.)</para>
|
||
|
||
<para>Certain PRs may be reassigned away from these generic
|
||
assignees by anyone. For assignees which are mailing lists,
|
||
please use the long form when making the assignment (e.g.,
|
||
<literal>freebsd-foo</literal> instead of <literal>foo</literal>);
|
||
this will avoid duplicate emails sent to the mailing list.</para>
|
||
|
||
<note>
|
||
<para>Here is a sample list of such entities; it is probably
|
||
not complete. In some cases, entries that have the short form are
|
||
<emphasis>aliases</emphasis>, not mailing lists.</para>
|
||
</note>
|
||
|
||
<table id=common-assignees-base>
|
||
<title>Common Assignees — base system</title>
|
||
<tgroup cols="3">
|
||
<thead>
|
||
<row>
|
||
<entry>Type</entry>
|
||
<entry>Suggested Category</entry>
|
||
<entry>Suggested Assignee</entry>
|
||
</row>
|
||
</thead>
|
||
|
||
<tbody>
|
||
<row>
|
||
<entry>problem specific to the &arm; architecture</entry>
|
||
<entry>kern</entry>
|
||
<entry>freebsd-arm</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>problem specific to the &mips; architecture</entry>
|
||
<entry>kern</entry>
|
||
<entry>freebsd-mips</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>problem specific to the &powerpc; architecture</entry>
|
||
<entry>kern</entry>
|
||
<entry>freebsd-ppc</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>problem with Advanced Configuration and Power
|
||
Management (&man.acpi.4;)</entry>
|
||
<entry>kern</entry>
|
||
<entry>freebsd-acpi</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>problem with Asynchronous Transfer Mode (ATM)
|
||
drivers</entry>
|
||
<entry>kern</entry>
|
||
<entry>freebsd-atm</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>problem with &firewire; drivers</entry>
|
||
<entry>kern</entry>
|
||
<entry>freebsd-firewire</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>problem with the filesystem code</entry>
|
||
<entry>kern</entry>
|
||
<entry>freebsd-fs</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>problem with the &man.geom.4; subsystem</entry>
|
||
<entry>kern</entry>
|
||
<entry>freebsd-geom</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>problem with the &man.ipfw.4; subsystem</entry>
|
||
<entry>kern</entry>
|
||
<entry>freebsd-ipfw</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>problem with Integrated Services Digital Network
|
||
(ISDN) drivers</entry>
|
||
<entry>kern</entry>
|
||
<entry>freebsd-isdn</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>problem with &linux; or SVR4 emulation</entry>
|
||
<entry>kern</entry>
|
||
<entry>freebsd-emulation</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>problem with the networking stack</entry>
|
||
<entry>kern</entry>
|
||
<entry>freebsd-net</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>problem with PicoBSD</entry>
|
||
<entry>kern</entry>
|
||
<entry>freebsd-small</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>problem with the &man.pf.4; subsystem</entry>
|
||
<entry>kern</entry>
|
||
<entry>freebsd-pf</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>problem with the &man.scsi.4; subsystem</entry>
|
||
<entry>kern</entry>
|
||
<entry>freebsd-scsi</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>problem with the &man.sound.4; subsystem</entry>
|
||
<entry>kern</entry>
|
||
<entry>freebsd-multimedia</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>problem with &man.sysinstall.8;</entry>
|
||
<entry>bin</entry>
|
||
<entry>freebsd-qa</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>problem with the system startup scripts
|
||
(&man.rc.8;)</entry>
|
||
<entry>kern</entry>
|
||
<entry>freebsd-rc</entry>
|
||
</row>
|
||
</tbody>
|
||
</table>
|
||
|
||
<table id=common-assignees-ports>
|
||
<title>Common Assignees — Ports Collection</title>
|
||
<tgroup cols="3">
|
||
<thead>
|
||
<row>
|
||
<entry>Type</entry>
|
||
<entry>Suggested Category</entry>
|
||
<entry>Suggested Assignee</entry>
|
||
</row>
|
||
</thead>
|
||
|
||
<tbody>
|
||
<row>
|
||
<entry>problem with the ports framework
|
||
(<emphasis>not</emphasis> with an individual port!)</entry>
|
||
<entry>ports</entry>
|
||
<entry>portmgr</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>port which is maintained by apache@FreeBSD.org</entry>
|
||
<entry>ports</entry>
|
||
<entry>apache</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>port which is maintained by eclipse@FreeBSD.org</entry>
|
||
<entry>ports</entry>
|
||
<entry>freebsd-eclipse</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>port which is maintained by gnome@FreeBSD.org</entry>
|
||
<entry>ports</entry>
|
||
<entry>gnome</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>port which is maintained by haskell@FreeBSD.org</entry>
|
||
<entry>ports</entry>
|
||
<entry>haskell</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>port which is maintained by java@FreeBSD.org</entry>
|
||
<entry>ports</entry>
|
||
<entry>freebsd-java</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>port which is maintained by kde@FreeBSD.org</entry>
|
||
<entry>ports</entry>
|
||
<entry>kde</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>port which is maintained by
|
||
openoffice@FreeBSD.org</entry>
|
||
<entry>ports</entry>
|
||
<entry>freebsd-openoffice</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>port which is maintained by perl@FreeBSD.org</entry>
|
||
<entry>ports</entry>
|
||
<entry>perl</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>port which is maintained by python@FreeBSD.org</entry>
|
||
<entry>ports</entry>
|
||
<entry>freebsd-python</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>port which is maintained by x11@FreeBSD.org</entry>
|
||
<entry>ports</entry>
|
||
<entry>freebsd-x11</entry>
|
||
</row>
|
||
</tbody>
|
||
</table>
|
||
|
||
<para>Ports PRs which have a maintainer who is a ports committer
|
||
may be reassigned by anyone (but note that not every &os;
|
||
committer is necessarily a ports committer, so you cannot
|
||
simply go by the email address alone.)
|
||
</para>
|
||
|
||
<para>For other PRs, please do not reassign them to individuals
|
||
(other than yourself) unless you are certain that the assignee
|
||
really wants to track the PR. This will help to avoid the
|
||
case where no one looks at fixing a particular problem
|
||
because everyone assumes that the assignee is already working
|
||
on it.</para>
|
||
|
||
</section>
|
||
|
||
<section id="pr-assigned">
|
||
<title>Assigned PRs</title>
|
||
|
||
<para>If a PR has the <literal>responsible</literal> field set
|
||
to the username of a FreeBSD developer, it means that the PR
|
||
has been handed over to that particular person for further
|
||
work.</para>
|
||
|
||
<para>Assigned PRs should not be touched by anyone but the
|
||
assignee. If you have comments, submit a followup. If for
|
||
some reason you think the PR should change state or be
|
||
reassigned, send a message to the assignee. If the assignee
|
||
does not respond within two weeks, unassign the PR and do as
|
||
you please.</para>
|
||
</section>
|
||
|
||
<section id="pr-dups">
|
||
<title>重複的 PR</title>
|
||
|
||
<para>If you find more than one PR that describe the same issue,
|
||
choose the one that contains the largest amount of useful
|
||
information and close the others, stating clearly the number
|
||
of the superseding PR. If several PRs contain non-overlapping
|
||
useful information, submit all the missing information to one
|
||
in a followup, including references to the others; then close
|
||
the other PRs (which are now completely superseded).</para>
|
||
</section>
|
||
|
||
<section id="pr-stale">
|
||
<title>Stale PRs</title>
|
||
|
||
<para>A PR is considered stale if it has not been modified in more
|
||
than six months. Apply the following procedure to deal with
|
||
stale PRs:</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>If the PR contains sufficient detail, try to reproduce
|
||
the problem in <literal>-CURRENT</literal> and
|
||
<literal>-STABLE</literal>. If you succeed, submit a
|
||
followup detailing your findings and try to find someone
|
||
to assign it to. Set the state to <quote>analyzed</quote>
|
||
if appropriate.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>If the PR describes an issue which you know is the
|
||
result of a usage error (incorrect configuration or
|
||
otherwise), submit a followup explaining what the
|
||
originator did wrong, then close the PR with the reason
|
||
<quote>User error</quote> or <quote>Configuration
|
||
error</quote>.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>If the PR describes an error which you know has been
|
||
corrected in both <literal>-CURRENT</literal> and
|
||
<literal>-STABLE</literal>, close it with a message
|
||
stating when it was fixed in each branch.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>If the PR describes an error which you know has been
|
||
corrected in <literal>-CURRENT</literal>, but not in
|
||
<literal>-STABLE</literal>, try to find out when the person
|
||
who corrected it is planning to MFC it, or try to find
|
||
someone else (maybe yourself?) to do it. Set the state to
|
||
<quote>feedback</quote> and assign it to whomever will do
|
||
the MFC.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>In other cases, ask the originator to confirm if
|
||
the problem still exists in newer versions. If the
|
||
originator does not reply within a month, close the PR
|
||
with the notation <quote>Feedback timeout</quote>.</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</section>
|
||
|
||
<section id="pr-misfiled">
|
||
<title>Misfiled PRs</title>
|
||
|
||
<para>GNATS is picky about the format of a submitted bug report.
|
||
This is why a lot of PRs end up being <quote>misfiled</quote> if
|
||
the submitter forgets to fill in a field or puts the wrong sort of
|
||
data in some of the PR fields. This section aims to provide most
|
||
of the necessary details for FreeBSD developers that can help them to
|
||
close or refile these PRs.</para>
|
||
|
||
<para>When GNATS cannot deduce what to do with a problem report
|
||
that reaches the database, it sets the responsible of the PR to
|
||
<literal>gnats-admin</literal> and files it under the
|
||
<literal>pending</literal> category. This is now a
|
||
<quote>misfiled</quote> PR and will not appear in bug report
|
||
listings, unless someone explicitly asks for a list of all the
|
||
misfiled PRs. If you have access to the FreeBSD cluster
|
||
machines, you can use <command>query-pr</command> to view a
|
||
listing of PRs that have been misfiled:</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>Commonly PRs like the ones shown above are misfiled for one
|
||
of the following reasons:</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>A followup to an existing PR, sent through email, has
|
||
the wrong format on its <literal>Subject:</literal>
|
||
header.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>A submitter sent a Cc: to a mailing list and someone
|
||
followed up to that post instead of the email issued by
|
||
GNATS after processing. The email to the list will not
|
||
have the category/PRnumber tracking tag. (This is why we
|
||
discourage submitters from doing this exact thing.)</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>When completing the &man.send-pr.1; template, the submitter
|
||
forgot to set the category or class of the PR to a proper
|
||
value.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>When completing the &man.send-pr.1; template, the submitter
|
||
set Confidential to <literal>yes</literal>. (Since we allow
|
||
anyone to mirror GNATS via <application>cvsup</application>,
|
||
our PRs are public information. Security alerts should
|
||
therefore not be sent via GNATS but instead via email to
|
||
the Security Team.)</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>It is not a real PR, but some random message sent to
|
||
<email>bug-followup@FreeBSD.org</email> or
|
||
<email>freebsd-gnats-submit@FreeBSD.org</email>.</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<section id="pr-misfiled-followups">
|
||
<title>Followups misfiled as new PRs</title>
|
||
|
||
<para>The first category of misfiled PRs, the one with the wrong
|
||
subject header, is actually the one that requires the greatest
|
||
amount of work from developers. These are not real PRs,
|
||
describing separate problem reports. When a reply is received
|
||
for an existing PR at one of the addresses that GNATS
|
||
<quote>listens</quote> to for incoming messages, the subject
|
||
of the reply should always be of the form:</para>
|
||
|
||
<programlisting>Subject: Re: category/number: old synopsis text</programlisting>
|
||
|
||
<para>Most mailers will add the
|
||
<quote><literal>Re: </literal></quote> part when you
|
||
reply to the original mail message of a PR. The
|
||
<quote><literal>category/number: </literal></quote> part
|
||
is a GNATS-specific convention that you have to manually
|
||
insert to the subject of your followup reports.</para>
|
||
|
||
<para>Any FreeBSD developer, who has direct access to the GNATS
|
||
database, can periodically check for PRs of this sort and move
|
||
interesting bits of the misfiled PR into the audit trail of
|
||
the original PR (by posting a proper followup to a bug report
|
||
to the address &a.bugfollowup;). Then
|
||
the misfiled PR can be closed with a message similar
|
||
to:</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>Searching with <command>query-pr</command> for the
|
||
original PR, of which a misfiled followup is a reply, is as
|
||
easy as running:</para>
|
||
|
||
<screen>&prompt.user; query-pr -q -y "some text"</screen>
|
||
|
||
<para>After you locate the original PR and the misfiled
|
||
followups, use the <option>-F</option> option of
|
||
<command>query-pr</command> to save the full text of all the
|
||
relevant PRs in a &unix; mailbox file, i.e.:</para>
|
||
|
||
<screen>&prompt.user; <userinput>query-pr -F 52458 52474 > mbox</userinput></screen>
|
||
|
||
<para>Now you can use any mail user agent to view all the PRs
|
||
you saved in <filename>mbox</filename>. Copy the text of all
|
||
the misfiled PRs in a followup to the original PR and make
|
||
sure you include the proper <literal>Subject:</literal>
|
||
header. Then close the misfiled PRs. When you close the misfiled
|
||
PRs remember that the submitter receives a mail notification that
|
||
his PR changed state to <quote>closed</quote>. Make sure you
|
||
provide enough details in the log about the reason of this state
|
||
change. Typically something like the following is ok:</para>
|
||
|
||
<programlisting>Followup to ports/45364 misfiled as a new PR.
|
||
This was misfiled because the subject did not have the format:
|
||
|
||
Re: ports/45364: ...</programlisting>
|
||
|
||
<para>This way the submitter of the misfiled PR will know what to
|
||
avoid the next time a followup to an existing PR is sent.</para>
|
||
</section>
|
||
|
||
<section id="pr-misfiled-format">
|
||
<title>PRs misfiled because of missing fields</title>
|
||
|
||
<para>The second type of misfiled PRs is usually the result of a
|
||
submitter forgetting to fill all the necessary fields when
|
||
writing the original PR.</para>
|
||
|
||
<para>Missing or bogus <quote>category</quote> or
|
||
<quote>class</quote> fields can result in a misfiled report.
|
||
Developers can use &man.edit-pr.1; to change the category or
|
||
class of these misfiled PRs to a more appropriate value and
|
||
save the PR.</para>
|
||
|
||
<para>Another common cause of misfiled PRs because of formatting
|
||
issues is quoting, changes or removal of the
|
||
<command>send-pr</command> template, either by the user who
|
||
edits the template or by mailers which do strange things to
|
||
plain text messages. This does not happen a lot of the time,
|
||
but it can be fixed with <command>edit-pr</command> too; it
|
||
does require a bit of work from the developer who refiles the
|
||
PR, but it is relatively easy to do most of the time.</para>
|
||
</section>
|
||
|
||
<section id="pr-misfiled-notpr">
|
||
<title>Misfiled PRs that are not really problem reports</title>
|
||
|
||
<para>Sometimes a user wants to submit a report for a problem
|
||
and sends a simple email message to GNATS. The GNATS scripts
|
||
will recognize bug reports that are formatted using the
|
||
&man.send-pr.1; template. They cannot parse any sort of email
|
||
though. This is why submissions of bug reports that are sent
|
||
to <email>freebsd-gnats-submit@FreeBSD.org</email> have to
|
||
follow the template of <command>send-pr</command>, but email
|
||
reports can be sent to &a.bugs;.</para>
|
||
|
||
<para>Developers that come across PRs that look like they should have
|
||
been posted to &a.bugs.name; or some other list should close the
|
||
PR, informing the submitter in their state-change log why this
|
||
is not really a PR and where the message should be posted.</para>
|
||
|
||
<para>The email addresses that GNATS listens to for incoming PRs
|
||
have been published as part of the FreeBSD documentation, have
|
||
been announced and listed on the web-site. This means that
|
||
spammers found them. Spam messages
|
||
that reach GNATS are promptly filed
|
||
under the <quote>pending</quote> category until someone looks
|
||
at them. Closing one of these with &man.edit-pr.1; is very
|
||
annoying though, because GNATS replies to the submitter and
|
||
the sender's address of spam mail is never valid these days.
|
||
Bounces will come back for each PR that is closed.</para>
|
||
|
||
<para>Currently, with the installation of some antispam filters
|
||
that check all submissions to the GNATS database, the amount
|
||
of spam that reaches the <quote>pending</quote> state is very
|
||
small.</para>
|
||
|
||
<para>All developers who have access to the FreeBSD.org cluster
|
||
machines are encouraged to check for misfiled PRs and immediately
|
||
close those that are spam mail. Whenever you close one of
|
||
these PRs, please do the following:
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>Set Category to <literal>junk</literal>.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>Set Confidential to <literal>no</literal>.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>Set Responsible to yourself (and not, e.g.,
|
||
<literal>freebsd-bugs</literal>, which merely
|
||
sends more mail).</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>Set State to <literal>closed</literal>.</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<para>Junk PRs are not
|
||
backed up, so filing spam mail under this category makes it
|
||
obvious that we do not care to keep it around or waste disk
|
||
space for it. If you merely close them without changing the
|
||
category, they remain both in the master database and in
|
||
any copies of the database mirrored through
|
||
<application>cvsup</application>.</para>
|
||
</section>
|
||
</section>
|
||
</section>
|
||
|
||
<section id="references">
|
||
<title>延伸閱讀</title>
|
||
|
||
<para>下面這是在寫、處理 PR 時，可以參考的資料。當然很明顯，這份清單仍須補充。</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para><ulink
|
||
url="&url.articles.problem-reports;/article.html">How to
|
||
Write FreeBSD Problem Reports</ulink>—給 PR 回報者用的參考原則。</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</section>
|
||
</article>
|