send-pr使用Howto --- HD

1. send-pr使用Howto --- HD

1.1. 前言

我们在这里要讲讲send-pr这个有趣的工具,它最重要的工作是向FreeBSD的GNATS提供问题报告。 FreeBSD依靠这些报告才真正的运行稳定并一步步的状大起来的。既然提到了GNATS,哪么我们简单的说说GNATS。

GNATS 是大名鼎鼎的 GNU 维护和使用的 Bug 跟踪系统。GNATS 将受管理的缺陷叫做"Problem Report"(问题报告), 简称为 "PR"。用户可以直接使用 Email 向系统提交 PR,亦可以使用基于 WEB 的图形界面提交。

gnat 在英文字典中含义为:“小昆虫,小烦扰”,其读音中 g 不发音,而单词 GNATS 中的 G 是发音的。

FreeBSD正是使用了GNATS这个系统来完成了针对于FreeBSD操作系统这个“庞然大物”的跟踪与维护。 由于种种原因,FreeBSD关闭了基于Web的问题提交界面, 同时也指出了请大家务必使用在每台FreeBSD中都包括的send-pr工具来提交问题。 也可以说send-pr这个小工具是分布于每台FreeBSD机器上的FreeBSD GNATS系统的客户端。

1.2. PR的构成

当我们使用send-pr时就会对一个PR进行编辑,一个初始的默认PR如下:

SEND-PR: -*- send-pr -*-
SEND-PR: Lines starting with `SEND-PR' will be removed automatically, as
SEND-PR: will all comments (text enclosed in `<' and `>').
SEND-PR:
SEND-PR: Please consult the following URL if you are not sure how to
SEND-PR: fill out a problem report:
SEND-PR: http://www.freebsd.org/doc/en/articles/problem-reports/
SEND-PR:
SEND-PR: Note that the Synopsis field is mandatory.
SEND-PR:
SEND-PR: Please note that (unless you state otherwise) if your report
SEND-PR: includes a patch then it will be taken under the same license as
SEND-PR: the one on the file(s) you want to change.
SEND-PR:
SEND-PR: BE ADVISED THAT FREEBSD PROBLEM REPORTS ARE PUBLIC INFORMATION AND
SEND-PR: WILL BE PUBLISHED AS-IS ON THE PROJECT'S MAILING LISTS AND WEB SITES.
SEND-PR: DO NOT SUBMIT ANY INFORMATION YOU DO NOT WANT MADE PUBLIC.
SEND-PR:
SEND-PR: If you wish to submit a problem report confidentially, then contact
SEND-PR: the FreeBSD bugmaster ([email protected]) to arrange for a
SEND-PR: relevant developer to be contacted.
SEND-PR:
SEND-PR: For sensitive security issues, consider contacting the FreeBSD
SEND-PR: security officer team ([email protected]) directly.
SEND-PR:
SEND-PR: Choose from the following categories:
SEND-PR:
SEND-PR: advocacy  alpha     amd64     bin       conf      docs
SEND-PR: gnu       i386      ia64      java      kern      misc
SEND-PR: ports     powerpc   sparc64   standards www
SEND-PR:
To: [email protected]
From: HuangDong <hd>
Reply-To: HuangDong <hd>
Cc:
X-send-pr-version: 3.113
X-GNATS-Notify:

        
>Submitter-Id:  current-users
>Originator:    HuangDong
>Organization:  <organization of PR author (multiple lines)>       
>Confidential:  no <FreeBSD PRs are public data>
>Synopsis:      <synopsis of the problem (one line)>
>Severity:      <[ non-critical | serious | critical ] (one line)>     
>Priority:      <[ low | medium | high ] (one line)>
>Category:      <choose from the list of categories above (one line)>
>Class:         <[ sw-bug | doc-bug | change-request | update | maintainer-update ] (one line)>
>Release:       FreeBSD 4.9-STABLE i386
>Environment:
System: FreeBSD mms1.lxhd.com 4.9-STABLE FreeBSD 4.9-STABLE #0: Thu Nov 13 16:58:42 CST 2003 roo
[email protected]:/usr/obj/usr/src/sys/HDSERVER i386


        <machine, os, target, libraries (multiple lines)>
>Description:
        <precise description of the problem (multiple lines)>
>How-To-Repeat:     
        <code/input/activities to reproduce the problem (multiple lines)>
>Fix:

        <how to correct or work around the problem, if known (multiple lines)>

每一个PR中都会包括的内容如下:

Mail headers 就像是电子邮件头一样的协定字符串。

GNATS fields 一个字段就是数据库中的字段一样,由'>'开始,最后有一个':'。 一个字段的内容类型可能是:文字(TEXT),数字(ENUMERATED其实是C中的enum,所以可以是代表数字的文字), 或多行文字(MULTITEXT)。

需要注意的是在这个PR中,最开始的'SEND-PR'开头的行都会在进库之前被取消,相当于注释。 FreeBSD通过SEND-PR部分来告诉大家与PR时的一些相关信息。

1.3. 使用send-pr

命令行的send-pr经常需要使用的参数是'-a',它的意思是将一个文件作为附件同PR一起提交给GNATS。如下所示:

send-pr -a /var/tmp/dmsg -a /etc/rc.conf

这样就将'/var/tmp/dmsg'和'/etc/rc.conf'作为附件与PR一起提交给了GNATS了。

当然也可以将PR提前写好,直接让send-pr读取一个文本文件直接提交:

send-pr -a /var/tmp/dmsg -a /etc/rc.conf -f ~/myprob

一旦在命令行输入send-pr命令后,它会调出vi来让提交者编辑一个PR。它的内容就与上节中的内容相同。 就像它在注释中所说,我们可以从 http://www.freebsd.org/doc/en/articles/problem-reports/ 得到问题提交的一些说明和技巧。我由其推荐大家先读一下 http://www.freebsd.org/doc/en/articles/problem-reports/pr-writing.html 这一段内容,它说明了如何来去写一个PR的内容。我们下面对每一项进行说明:

To: [email protected]

这是邮件目标地址,向FeeBSD提交的地址是相同的,不用改变它。

From: [email protected]
Reply-To: [email protected]
Cc: [email protected]

提交PR的人的mail地址以及抄送人的Mail地址,抄送给自己有时也是一个好的主意,因为这样可以存储一个备份。

X-send-pr-version: 3.113
X-GNATS-Notify:

这是GNATS使用的信息,可以不写。

>Submitter-Id:  current-users

不要修改这个参数,即使你使用的是FreeBSD-Stable,缺省的参数current-users是唯一正确的数值。

>Organization:  FreeBSD China

写这个PR的组织,呵呵,看来有很多或是什么都没有的空白都有可能哟。

>Confidential:  no

这个使用它的默认no好了。

>Synopsis: System startup error.

这里是对问题的一个简短的提要说明。请注意,这个字段一定不能空着。

>Severity: non-critical

在这里使用non-critical、serious或是critical来说明提交问题的严重性。

>Priority: 

在这里使用low | medium | high


© 2003-2004, 技术天空