为 FreeBSD 提供帮助

$FreeBSD: doc/zh_CN.GB2312/articles/contributing/article.sgml,v 1.6 2010/02/12 23:30:05 delphij Exp $

FreeBSD 是 FreeBSD基金会的注册商标

IEEE, POSIX, 和 802 是 Institute of Electrical and Electronics Engineers, Inc. 在美国的注册商标。

许多制造商和经销商使用一些称为商标的图案或文字设计来彰显自己的产品。 本文档中出现的, 为 FreeBSD Project 所知晓的商标,后面将以 '™' 或 '®' 符号来标注。

  无论是作为个人还是组织机构,如果您希望为FreeBSD项目提供帮助, 都可以在本文中找到合适的方法。


目录
1 我们的需求
2 如何提供帮助

  您希望给 FreeBSD 项目做点什么吗? 太好了, 我们欢迎您。 FreeBSD 正是 依靠 广大用户的贡献才得以发展壮大的。 我们不仅非常感谢您所做的贡献,而且,这些工作对于 FreeBSD 的持续发展也至关重要。

  也许与您想象的不同, 您既不必是一名出色的程序员, 也无须和 FreeBSD 核心团队成员有很好的私交, 我们会一视同仁的对待您的工作。 FreeBSD 的开发人员遍布全球, 大家技术专长各异, 年龄分布也非常广泛。 每天, 我们都在面对持续增长的工作而苦于没有足够的人手, 因此我们随时欢迎您的帮助。

  FreeBSD 项目处理的是一个完整的操作系统环境, 而不只是一个内核或是一些零散的工具包。 因此, 我们的 TODO 任务列表里包含各种各样的工作, 从文档、用户测试、演示, 到系统安装程序和高度专业的内核开发。 因此无论您的技术水平如何, 从事何种领域, 都可以帮助这个项目。

  我们鼓励从事和 FreeBSD 相关工作的企业和我们联系。 您需要一些特殊的扩展来使您的产品运转起来么? 您会发现我们很乐意答应您的请求, 除非是特别稀奇古怪的。 您是否正从事相关的增值业务? 让我们来帮助您吧, 我们也许可以在其中的某些方面相互协作。 自由软件世界正在努力打破旧有的关于软件开发、 销售和维护的框框, 我们希望恳请您至少能给它一次机会。


1 我们的需求

  下面列出了一些需要完成的任务和子项目, 它们基本上可以被等同于 TODO(任务列表) 列表, 以及用户的要求。


1.1 正在进行中的非开发任务

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

  1. 您可以经常通读FAQ和手册, 如果您发现了繁琐的解释, 或者是过时的知识, 甚至完全不正确的地方, 都请告诉我们。 如果您能顺手把他们改过来那就更好了 (SGML其实并不难学, 但我们也不反对您直接提交 ASCII 的版本)。

  2. 帮助我们把 FreeBSD 文档翻译成您的母语。 如果您的母语版本已经存在了, 您也可以翻译一些其他的文档或者检查那些已有的文档是否是最新更新过的。 您可以先简单看看 FreeBSD 文档计划中有关 翻译的常见问题。 参加翻译工作并不是说您要孤军奋战翻译所有的 FreeBSD 文档。 作为一个志愿者, 做多少工作完全取决于您的意愿。 一旦某个人开始翻译了, 其他人几乎一定会参与到这些工作中来。 如果您只有有限的时间或者精力去翻译部分文档, 您可以首先去翻译安装指南。

  3. 阅读 FreeBSD 一般问题邮件列表 并偶尔看一看 the comp.unix.bsd.freebsd.misc newsgroup (甚至有规律地这样做)。 与别人分享您的专业知识, 并帮助他们解决问题是一件令人愉悦的事情; 有些时候您甚至可以在这个过程中学到一些新东西! 这些论坛有时也会为您提供一些有价值的主意。


1.2 正在进行的开发任务

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

  1. 如果您正在运行 FreeBSD-CURRENT 版本并且有一条高速的 Internet接入线路, 您可以访问 current.FreeBSD.org, 这里每天会有一个新版本 ── 如果您有空, 您可以隔三岔五地下载一份并且安装它, 其间如果出了什么问题,请告诉我们。

  2. 阅读 FreeBSD 问题报告邮件列表。 您可能会为这些问题提供具有建设性意义的评论, 或者帮忙测试一些补丁。 此外, 您甚至可以尝试修正其中的一些问题。

  3. 如果您知道有一些修正已经在 -CURRENT 上成功地进行, 但在经过一段时间之后仍然没有合并到 -STABLE (通常是 2周左右), 给相关的 committer 发一封礼貌的提示信。

  4. 将第三方软件加入到源代码中的 src/contrib 目录。

  5. 确保 src/contrib 中的代码是最新的

  6. 以更高的警告级别构建源代码 (或一部分源代码) 并清理这些警告。

  7. 更新那些在 ports 中使用过时的东西, 例如 gets() 或包含 malloc.h 所产生的警告。

  8. 如果您制作了 ports, 并进行了一些针对 FreeBSD 的改动, 将您的补丁发回给原作者 (这样下次升级时您的工作会变得轻松一些)。

  9. 获取一份正式的标准, 如 POSIX® 的副本。 您可以在 FreeBSD C99 & POSIX 标准顺应项目 网站上得到相关的链接。 将 FreeBSD 的行为同标准进行比较。 如果与标准不同, 特别是那些细节地方的微小差异, 请发送一个关于它的 PR (问题报告)。 如果可能, 请指出如何修正它, 并随 PR 提交补丁。 如果您认为标准有问题, 请向标准化团体要求对其进行重新的考虑。

  10. 为这份列表建议更多的内容!


1.3 查看整个 PR 数据库

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

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


1.4 从 “点子” 网页上认领项目

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


2 如何提供帮助

  帮助改进系统基本上可以分为 5 类:


2.1 错误报告和一般的注解

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

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

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

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

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


2.2 对于文档的修订

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


2.3 对于现有源代码的修改

  在现有代码上进行修改或增加功能在某种程度上是需要更多技巧的事情, 并且还和您对于目前 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) 以了解关于编码习惯和约定的详情。 如果您了解这些约定, 则对我们来说将是极大的帮助。


2.4 新代码或重要的增值软件包

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

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

  1. BSD 版权。 我们倾向于使用这类授权的代码, 因为它 “不附加多余的条件”, 因而更能够吸引商业企业使用。 FreeBSD 并不反对商业公司使用它的代码, 相反, 我们积极地鼓励商业公司使用我们的代码, 当然, 如果它们最终把一部分代码重新捐赠给 FreeBSD 就更好了。

  2. GNU General Public License, 或简称 “GPL”。 我们并不很欢迎使用这样授权的代码, 因为商业公司使用它需要做更多的工作。 不过, 由于很多使用 GPL 授权的代码目前是无法避免的 (编译器、 汇编器, 文本排版程序等等), 拒绝使用所有采用这样授权的软件是很不明智的。 采用 GPL 授权的代码会被放到源代码的一些专门的位置, 例如 /sys/gnu/usr/src/gnu, 以方便那些使用 GPL 代码可能会给他们带来问题的人识别。

  使用其它授权的代码在进入 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 也可以找到此授权的副本。


2.5 资金、 硬件或 Internet 接入

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


2.5.1 捐款

  FreeBSD 基金会是一个非营利的、 有课税豁免权的基金会, 建立这个基金会的目标是为了让 FreeBSD Project 能够达成更加长远的目标。 作为 501(c)3 实体, 一般而言基金会可以免予上缴美国联邦收入税, 以及科罗拉多州收入税。 通常对于课税豁免的实体进行捐赠, 可以折抵联邦收入中应课税部分的金额。

  您可以把支票寄往:

    The FreeBSD Foundation
    7321 Brockway Dr.
    BoulderCO 80303
    USA
  



  FreeBSD 基金会现在可以通过 PayPal 从网上接受捐款。 如果您想向基金会捐款, 请访问它的 web 站点

  关于 FreeBSD 基金会的更多详情, 可以在 FreeBSD 基金会 -- 介绍 找到。 要联络基金会, 请发送电子邮件到


2.5.2 捐赠硬件

  FreeBSD 计划欢迎任何人捐赠可以使用的硬件。 如果您有兴趣捐赠硬件, 请联系 捐赠联络人办公室


2.5.3 捐赠 Internet 接入

  我们欢迎新的 FTP、 WWW 或 cvsup 镜像。 如果您希望成为这样的镜像, 请参见 如何架设 FreeBSD 镜像 一文, 以了解进一步的情况。


本文档和其它文档可从这里下载:ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/.

如果对于FreeBSD有问题,请先阅读文档,如不能解决再联系<[email protected]>.
关于本文档的问题请发信联系 <[email protected]>.