为 FreeBSD 提供帮助

很多参加FreeBSD项目的人不是程序员。 这个项目里有文档撰写者、 网页设计师、 以及技术支持人员。 对于这些志愿者来说， 他们只需要贡献一些时间， 并且具有学习的意愿。

列在这里的大部分任务都需要您投入可观的时间， 或者需要您在 FreeBSD 内核方面有丰富的知识， 或者两者都要。 当然这里也有很多重要的任务也许您一个 “周末开发人员” 就可以干完。

FreeBSD PR 列表 展示了所有当前处于活跃状态的问题报告， 以及由 FreeBSD 用户提交的改进建议。 PR 数据库同时包括了开发人员和非开发人员的任务。 查看那些尚未解决的 PR， 并看看是否有您感兴趣的任务。 这其中可能有一些是非常简单的问题， 只需要看一看并确认 PR 是正确的。 另外一些可能会非常复杂， 或者完全没有包括任何修正。

首先看一看那些还没有人接手的 PR。 如果 PR 已经分配给了其它人， 但看起来是您能够处理的， 您可以给那个人发信， 并询问您是否可以提供帮助 ── 他们可能已经有了可供测试的补丁， 或有一些可供讨论的意见。

FreeBSD 志愿者项目和点子清单 也是提供给愿意为 FreeBSD 项目做出贡献的人们的。 这张清单一直在被定期更新着， 包含了对程序员和非程序员有用的每个项目的信息。

通常， 一般意义上的 技术想法和建议应该发到 FreeBSD 技术讨论邮件列表。 同样地， 对于这些东西有兴趣的人 (当然， 他们同时还要能够容忍 大量的 邮件！) 可以考虑订阅 FreeBSD 技术讨论邮件列表。 参见 FreeBSD 使用手册 以了解关于这个邮件列表， 以及其它邮件列表的详细情况。

如果您发现了 bug 或者想要提交某些修改， 请通过 send-pr(1) 程序或使用 基于 WEB 的提交页面 来提交。 请试着填写 bug 报告的每一项。 一般来说， 我们建议在 bug 报告中直接附上补丁， 除非它超过了 65KB。 如果补丁可以直接应用到源代码上， 则建议您在报告的 synopsis 一栏写上 [PATCH]。 在附带补丁时， 请 不要 通过复制和粘贴来进行， 因为这样做会把 tab 变成空格， 结果补丁很可能就不能用了。 如果补丁超过 20KB 很多， 应考虑将其压缩 (例如使用 gzip(1) 或 bzip2(1)) 之后用 uuencode(1) 进行编码之后再放进您的问题报告中。

一旦报告被存档， 您会收到一封确认邮件以及一个事件追踪编号。 请保留这个编号， 因为您可以在之后使用这个编号， 发邮件到 <bug-followup@FreeBSD.org> 来提供关于该事件的进一步信息。 您需要做的是将编号放到邮件的标题中， 例如 "Re: kern/3377"。 关于同一问题更进一步的情况应该通过这种方式来提交。

如果您在一段时间之后仍然没有收到确认信 (超过 3 天甚至 1 周， 这取决于您的邮件服务) 或者由于某种原因无法使用 send-pr(1) 命令， 则可以发信给 FreeBSD 问题报告邮件列表 要求别人代您发送它。

请参见 这篇文章 了解如何撰写好的问题报告。

对于文档的修改由 FreeBSD 文档计划邮件列表 来审查。 请参见 FreeBSD 文档计划初级读本 来获得完整的指导。 请按照 第 2.1 节 “错误报告和一般的注解” 中介绍的方法使用 send-pr(1) 来发送新的文档或者对于现有文档的完善 (哪怕是很小的改进也是欢迎的！)。

在现有代码上进行修改或增加功能在某种程度上是需要更多技巧的事情， 并且还和您对于目前 FreeBSD 的开发现状的了解有关。 有多种方式可以得到被称作 “FreeBSD-CURRENT” 的 FreeBSD 开发版本， 您可以通过它来了解最近的开发情况。 请参见 FreeBSD 使用手册 来了解使用 FreeBSD-CURRENT 的进一步详情。

在旧的代码上进行修改， 则通常可能由于代码已经过时， 或与新的开发版本差异太大而无法被重新集成到 FreeBSD 中。 如果您订阅了 FreeBSD 公告邮件列表 以及 FreeBSD-CURRENT 邮件列表 邮件列表， 则可以通过它们来大体了解目前的开发状态。

假如说您能够基于尽可能新的代码来完成您的修改， 则下一步要做的事情就是生成您所进行的修改的差异文件， 并将它发给 FreeBSD 的维护人员。 这项工作可以通过 diff(1) 命令来完成。

提交补丁时推荐的 diff(1) 格式是一致差异 (unified diff)， 它可以通过 diff -u 来生成。 不过， 如果您修改了大量的代码， 则使用 diff -c 来生成的上下文格式 (context diff) 的差异可能更容易阅读， 因而推荐使用。

例如：

% diff -c oldfile newfile

或者

% diff -c -r olddir newdir

将分别生成给定文件或目录结构的 context diff。

类似地，

% diff -u oldfile newfile

或

% diff -u -r olddir newdir

的作用与前面的类似， 但采用的格式是 unified diff。

请参见 diff(1) 联机手册了解更多细节。

一旦您使用 diff(1) 生成了差异集 (可以使用 patch(1) 命令来测试一下)， 就可以提交它们， 以便被 FreeBSD 收录。 通过使用 第 2.1 节 “错误报告和一般的注解” 中所介绍的 send-pr(1) 程序就可以完成这项工作。 不要 只是把差异集发到 FreeBSD 技术讨论邮件列表， 否则它们可能会被丢掉！ 我们会非常感激您提交的修改 (这是一个志愿者项目！)； 因为我们都很忙， 因此有时不一定能够立即修正问题， 但 PR 数据库将一直保持着这些记录， 因此只要有人有了时间它们就能被改正了。 如果您的问题报告中包括补丁， 一定不要忘了在标题上用 [PATCH] 来强调一下。

如果您认为合适 (例如您添加、 删除或重命名了文件)， 还可以考虑使用 tar 来将文件打包， 然后用 uuencode(1) 来编码。 我们也欢迎用 shar(1) 创建的包。

如果您的修改可能存在潜在的争议， 例如， 您不确定与之相关的版权问题， 或者感觉需要经过更严格的复审才可以发布它们， 则应直接发给 FreeBSD 核心团队， 而不是通过 send-pr(1) 来发送。 FreeBSD 核心团队 是一个小组， 其成员更多的从事 FreeBSD 的日常工作。 需要注意的是， 这个小组也因此 很忙， 因此只有在非常必要的时候才应给他们写信。

请参考 intro(9) 和 style(9) 以了解关于编码习惯和约定的详情。 如果您了解这些约定， 则对我们来说将是极大的帮助。

如果您打算提供规模较大的代码， 或者为 FreeBSD 增加重要的新功能， 则可能必须将它们通过 uuencode 进行编码， 或传到某个 Web 或 FTP 站点， 以便更多的人能够得到它。 如果您没有这样的服务器， 请到相关的 FreeBSD 邮件列表提出， 看看是否有人愿意帮您放置它们。

对于大量的代码而言， 关于版权的问题肯定会被提出。 FreeBSD 基本系统中能够使用的版权声明包括：

使用其它授权的代码在进入 FreeBSD 之前必须经过慎重的复审和考虑。 采用包含严厉限制的商业授权的代码， 一般来说会被拒绝， 但我们鼓励这些代码的作者通过自己的渠道来发布它们。

要在您的成果上加入 “BSD式” 的版权， 请把下列文本放到每一个源文件的最开始部分， 并用适当的文字替换 %% 之间的文字。

Copyright (c) %%proper_years_here%%
        %%your_name_here%%, %%your_state%%  %%your_zip%%.
	All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer as
   the first lines of this file unmodified.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY %%your_name_here%% ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL %%your_name_here%% BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

        $Id$

为了方便您的使用， 在 /usr/share/examples/etc/bsd-style-copyright 也可以找到此授权的副本。

我们非常愿意接受各种形式的捐赠， 以进一步拓展 FreeBSD Project 的事业， 因为有您的支持， 像我们这样的志愿者努力才能够有更大的成就！ 捐赠硬件也非常重要， 因为这样能够帮助我们增加可以支持的硬件种类， 而我们中的很多人并没有足够的资金来购置这些硬件。