这份文档是为描述 Subversion 1.2 版本而编写的。如果您使用的是更新版本的 Subversion,我们强烈建议您访问 https://svnbooks.subversion.org.cn/ 并查阅与您的 Subversion 版本相符的版本。
Subversion 项目的官方信息来源当然是项目的网站,位于 http://subversion.tigris.org/。在那里您可以找到有关获取源代码访问权限和参与讨论列表的信息。Subversion 社区始终欢迎新成员。如果您有兴趣通过为源代码贡献更改来参与这个社区,这里有一些关于如何入门的提示。
社区参与的第一步是找到一种方法来掌握最新的情况。要最有效地做到这一点,您需要订阅主要开发者讨论列表 (<[email protected]>
) 和提交邮件列表 (<[email protected]>
)。即使只是粗略地关注这些列表,您也能了解重要的设计讨论,看到对 Subversion 源代码的实际更改,并见证对这些更改和拟议更改的同行评审。这些基于电子邮件的讨论列表是 Subversion 开发的主要交流媒介。请参阅网站的“邮件列表”部分,了解您可能感兴趣的其他与 Subversion 相关的列表。
但是,您如何知道需要做些什么呢?程序员通常怀着极大的帮助开发的意愿,却无法找到一个好的起点。毕竟,并非所有人都加入社区时已经决定了他们想解决的特定问题。但是,通过关注开发者讨论列表,您可能会看到关于现有错误或功能请求的提及,这些问题可能会特别引起您的兴趣。此外,在 Subversion 网站上的问题跟踪数据库中寻找未完成的、无人认领的任务也是一个好地方。在那里,您会找到已知错误和功能请求的当前列表。如果您想从简单的事情开始,请寻找标记为“小块”的问题。
要编辑代码,您需要拥有代码。这意味着您需要从公共 Subversion 源代码库中签出工作副本。尽管这听起来很简单,但这个任务可能有点棘手。由于 Subversion 的源代码是使用 Subversion 本身进行版本控制的,因此您实际上需要通过其他方法“引导”来获取工作 Subversion 客户端。最常见的方法包括下载最新的二进制分发版(如果您的平台有此分发版),或下载最新的源代码包并构建您自己的 Subversion 客户端。如果您从源代码构建,请确保阅读源代码树顶层的 INSTALL
文件以获取说明。
在您拥有一个可用的 Subversion 客户端后,您现在可以从 http://svn.collab.net/repos/svn/trunk/ 签出 Subversion 源代码库的工作副本:[46]
$ svn checkout http://svn.collab.net/repos/svn/trunk subversion A subversion/HACKING A subversion/INSTALL A subversion/README A subversion/autogen.sh A subversion/build.conf …
上面的命令将在当前工作目录中名为 subversion
的子目录中签出 Subversion 源代码的最新版本。显然,您可以根据需要调整最后一个参数。无论您将新的工作副本目录命名为什么,此操作完成后,您现在将拥有 Subversion 源代码。当然,您仍然需要获取一些辅助库(apr、apr-util 等) - 请参阅工作副本顶层的 INSTALL
文件以获取详细信息。
现在您拥有包含最新 Subversion 源代码的工作副本,您肯定会想浏览一下“Subversion 黑客指南”,该指南可以在工作副本中的 www/hacking.html
文件中找到,也可以在 Subversion 网站上找到 http://subversion.tigris.org/hacking.html。本指南包含有关为 Subversion 做贡献的一般说明,包括如何正确格式化您的源代码以与其他代码库保持一致,如何使用有效的更改日志消息描述您提出的更改,如何测试您的更改等等。Subversion 源代码库的提交权限是赚取的 - 这是精英治理。[47] “黑客指南”是在确保您提出的更改获得应得的赞赏而不因技术问题而被拒绝时的一项宝贵资源。
有了代码和社区政策理解,您就可以进行更改。最好尝试进行较小但相关的更改集,即使是以分阶段的方式处理较大的任务,也不要进行巨大的、全面的修改。如果您要完成的任务是妥善完成,那么您提出的更改越少,就越容易理解(因此也越容易审查)。在进行每组拟议更改后,您的 Subversion 树应该处于软件编译没有任何警告的状态。
Subversion 有一个相当全面的[48] 回归测试套件,并且您的拟议更改预计不会导致任何这些测试失败。通过运行 make check(在 Unix 中)从源代码树的顶部开始,您可以对您的更改进行健全性检查。让您的代码贡献被拒绝的最快方法(除了未能提供良好的日志消息之外)是提交会导致测试套件失败的更改。
在最佳情况下,您实际上会向该测试套件添加适当的测试,以验证您提出的更改按预期工作。事实上,有时一个人能做出的最佳贡献仅仅是添加新的测试。您可以为 Subversion 中当前起作用的功能编写回归测试,以防止将来可能在这些区域触发失败的更改。此外,您还可以编写演示已知错误的新测试。为此,Subversion 测试套件允许您指定给定测试预计会失败(称为 XFAIL
),只要 Subversion 按预期失败,则测试结果为 XFAIL
本身就被认为是成功的。最终,测试套件越好,在诊断潜在的模糊回归错误上浪费的时间就越少。
在对源代码进行修改后,请撰写清晰简洁的日志消息,以描述这些更改以及原因。然后,向开发者列表发送一封电子邮件,其中包含您的日志消息和 svn diff(从您的 Subversion 工作副本的顶部开始)的输出。如果社区成员认为您的更改是可以接受的,则拥有提交权限(允许在 Subversion 源代码库中创建新修订版)的人员将把您的更改添加到公共源代码树中。请记住,直接向存储库提交更改的权限是根据功绩授予的 - 如果您证明了对 Subversion 的理解,编程能力和“团队精神”,您很可能会获得该权限。