如何提交FreeBSD ports 的更改 -- HD

1. 如何提交FreeBSD ports的更改

1.1. 什么是PR

改造任何BSD最好的资源就是它们自己。您可以看到开发人员并不急于提交一个补丁到CVS中, 却在邮件列表里面展示这些补丁,其实这些具备向CVS树提交代码权限的人是为了能够公开的讨论各种的解决方法的好处。 当很多改进被或多或少的支持的时候,这些人才会最终提交这些代码。 邮件列表并不是一个提交补丁的地方,但是却是一个讨论补丁的地方。

每个BSD项目都积极的寻求用户所做的各种贡献,并且拥有一个系统去接受和跟踪他们。补丁, 甚至是一个完美的补丁,如果直接发到列表上也会渐渐消失在邮件的存档中的。 通过一个适当的途径您可以有很大的机会获得提交者(committer)对您的工作的认可, 并且最终您成为一个正式的提交者。OpenBSD, NetBSD和FreeBSD都使用GNATS和send-pr或者sendbug。 它们都非常的相近;我将使用FreeBSD来做为一个例子。

GNATS是一个非常流行的问题跟踪数据库包。FreeBSD的版本可以从Web上面找到。 GNATS跟踪的是“问题报告”,或者叫做PR。一个PR只是一个简单的e-mail遵循一个特定的格式。

send-pr程序把邮件格式化成为进入GNATS系统的特定格式。它提供了一个问题报告的模板, 并且包含如何填写报告的指示。通过send-pr提交的补丁和建议将永久的记录下来。

这个步骤并不是为了那些例如“我的网卡不能工作了”之类的问题而做的, 像这类问题您就需要通过邮件列表或者列表存档来解决您的问题了。这个系统是为了补丁和debugging信息而准备的。

一个好的PR应该包括如何修正这个问题的足够信息,甚至是一个解决方案。如果您有空闲时间, 可以阅读一下开放的PR;您也许会发现这将给您很大的启发。就像我写的这个一样, 现在有1918个开放的PR可供查询。其中大部分的内容是非常好的,带有全面的debugging信息。 其他的那些,大概看看就行了,用处不大。

FreeBSD的FAQ里面有一个Dag-Erling C. Smørgrav写的笑话:“需要多少个freebsd-current的用户才能够换一个灯泡?” 一部分的答案是“3个人提交关于这个问题的PR,其中一个人把文档放在了错误的doc目录下并且只写了一句话‘这儿黑了’”。 当您对一个PR进行归档的时候,请记住这个笑话;包括那些debugging输出或者diff。

当您书写一个PR之前,您需要仔细的评估您遇到了那一类的问题,如果只是“这儿黑了!”这样的问题, 您就需要更深的挖掘一下问题的实质了。

send-pr命令实在是非常的简单。它使用了在$EDITOR中的一个文本模板。当您完成了模板, send-pr就为您把它发送到GNATS上去了。就是这么简单。

发送邮件在一些系统上是个问题。没准您正在使用拨号连接,并且所有邮件必须以来一个中央服务器来传送。 您的BSD系统也许并没有对发送e-mail进行配置。在这些情况下,您可以使用web界面来提交您的PR。

web界面包含了所有send-pr命令中的字段。它只有一个问题:它将破坏补丁中的格式。 这种情况,您可以使用一个邮件客户端来发送您PR中的后续部分。

您使用什么样的方法并不重要,问题是如何填写这个格式。让我们来搞定它!

1.2. 如何写一个PR

To, Subject,和Submitter-Id这三行可以单独空出来。

确认From这一行包含了一个正确地e-mail地址; GNATS或者一个committer将会使用这个地址来试图联系您。

Originator这行是您的名字,通常来源于您的环境。例如在Internet上面常用的昵称之类的, 其实这是一个写您真名的好地方。不过如果您的名字是“Doctor Web”也许提醒大家这是一个非常难于处理的问题。

类似的,您可以填写您的organization或者不填些它。

Confidential字段通常是设置为"no"。GNATS是一个公开的数据库。如果您在PR中提交一份机密信息, 您也许做错了些什么。

Synopsis行是最言简意赅的部分。书写一个简单的额,一行的对问题的描述。 开发者经常通过看这个来决定那个PR需要研究一下。一个类似“我的系统好笨!”的大纲将会评价为一个无用的PR而被关闭。 但像是“kernel panic under heavy NFS load, ddb attached”这样的就会更有机会引起开发者的注意。

如果您有一个补丁来修正这个问题,请在大纲里写上“PATCH”这个词。这基本上会获得立即的回应。

Severity字段给您三个选择。任选其一。按照您的情况:如果您把一个小bug列为“critical”的话, 您没准会给大家留下一个坏印象。很快的您就会发现,您提的的问题总是被大家忽略。

Priority字段是一个有点不太恰当的字段。因为也许这个问题对于您来说是非常紧急的, 别人却不这么看;所以开发者倾向于忽略这个字段。但是您仍然可以作为一个选项来设置它。 一个好的大纲将会比设置一个“high”优先级更容易获得好的回应,但是也许这能减轻您的压力。

Category字段有几个选项。其中一些是陈旧或者不明确的。如果您觉得一段GNU的代码有点问题, 例如,把一个PR归档到GNU类别里,也许您会获得一个类似这样的回应“去跟GNU的人说。” 最有用的类别是alpha,bin,conf,docs,i386,kern,misc和ports。 您可以查阅send-pr的man page来获得每个部分更加详细的信息。

Class字段是为了总体描述您的PR用的。这部分应该是最具有自我说明性的。 如果您可以让一个程序或者一个系统崩溃,它就是一个sw-bug。如果文档出现错误,它就是一个doc-bug。 如果您不喜欢某些工作,它就是一个change request(更改请求)。一个update是一个改进。 而maintainer-update意味着它是对于您所负责的一段代码的改进。

您的系统类型被自动填入Release字段。如果您在另外一个不同的系统上书写的PR, 就会出现一些问题,您就需要更正这个字段了。

最后,System字段内容是uname -a的输出。 您可以添加一些额外的信息到这个字段中去描述您系统中其他相关的部分。 例如机器是重负载的新闻服务器,您可以标出来。如果您摘录出一小段配置文件来证明一个bug,也可以放在这里。

Description字段是自由格式的,一段让您来描述关于这个问题细节的纯文本的部分。请 注意不要在这个部分里大喊大叫;只要描述发生了什么问题就好了。 包括debugger的输出或者是错误信息之类的,如果您有的话。

在How-To-Repeat(如何重现)中使用一小段代码,一系列说明,或者是如何重现这个问题的文字的描述。 一些PR这部分可以非常的简短--“阅读freebsd-questions一个星期并且注意一下这个问题有多没经常被问到” 就是一个进行doc修改的完美而合理的How-To-Repeat。其他的技术问题则需要更多的信息。

PR最重要的部分就是“FIX”下面的内容。如果您有一个补丁修正了一个问题,请放在这里。 如果您有一个工作区,请放在这里。任何您发现如何解决问题的方法都可以放在这里。

一个好的PR总是在Fix字段有些东西的。你的解决方法也许并没有被采纳, 但是这却体现出您曾经认真的思考过这个问题。FreeBSD通过邮件列表和web网站提供的不可思议的支持, 在您遇到困难的时候可能会使事实模糊不清,而解决问题的重任就落在了您的肩上。

如果您想做了一个diff的修正补丁,请使用context diff,就像这样:

diff -c yourfile originalfile > patch

这样将能充分的保留了上下文来保证能够正常的应用上去,并且保留了例如空格和制表符这样的格式。 不要剪切和复制补丁;这将覆盖掉制表符和空格。

当您保存并且退出您的编辑器,send-pr将会询问您是否想提交这个问题报告。 如果您认为您的PR包含了足够的解决这个问题的信息请您选择yes,您的系统将会把它寄出去。

1.3. 如何写好PR

无论使用什么方法来提交PR,您都将收到一封确认e-mail。标题包括PR的编号,通常就像“docs/22459”之类的,还有您的大纲。 任何发送到[email protected]带有subject行的将会被附加到相应的PR上面。 您可以通过一个有邮件系统的计算机来提交您的补丁。

相似的,任何对您补丁的回应都可以从PR中查询到。 您可以从这里http://www.freebsd.org/cgi/query-pr.cgi 检查您PR的状态。

现在您的建议已经发送到FreeBSD的系统中去了,它将永远的被跟踪。 当然不能保证您的建议会被采纳,或者您的问题会被修正。

一个恰当书写的PR将会被很快的提交并且关闭。我曾经提交过10个PR。九个被提交到代码中去并且关闭了。 第十个是/usr/src/contrib里面man page的一个微不足道的小错误,但那个区域负责的维护者拒绝修改这种小错误。 如果我能够使我的PR有90%的成功率关闭掉,那么任何人都可以。

如果您正好遇到了一个没人熟悉的系统问题,您的PR也许就会被荒废一段时间了。

如果您觉得您的PR好像被遗忘了,写一个友好的提示到相应的邮件列表中去。 给出您的PR编号和对它简单的解释,并且说明一下为什么这个很重要。 FreeBSD是由志愿者的努力支撑的,所以很可能会出现负责处理您的问题的那个志愿者忽略了您的PR这种情况。 很多FreeBSD的开发者都是专业的程序员,他们中的很多人工作和生活还是很忙的。

如果您的PR标注了critical bug,会吸引大家的注意力来修正它。 但是如果它实际上并不是一个非常重要的问题可能就需要等到一个适当的开发者有时间的时候才能处理了。

在某些情况下,您也许会发现当前的FreeBSD提交者中并没有能够给您提供更深层次意见的人。 如果某人为子系统提交了足够充分的补丁并不代表他了解并能维护这段代码。

这看起来也许需要做很多的工作来打补丁。 大部分FreeBSD提交者都是那些证明自己有丰富经验并且准确的使用send-pr的用户。

最后,您的PR将会被关闭掉。也许您的问题将会被解决。 或者,更有趣的,也许您的建议将会引发在freebsd-hackers的激烈讨论并且最终使FreeBSD变得更有趣。 无论那种情况,一个恰当的问题报告会让FreeBSD小组提供给您一个更好的操作系统。