概述 ¶

分支创建和管理 ¶

基于分支的开发并没有特别复杂。您从主干（或从最适合作为您的工作来源和目标的分支）创建一个分支，并在该分支上进行工作。Subversion 的合并跟踪功能极大地帮助减少了以这种方式工作所需的思维负担，因此强烈建议您充分利用该功能（通过使用 Subversion 1.5 或更新的客户端，并对分支的根目录执行所有合并）。

有关分支日志消息的策略，请注意有关 编写日志消息 的部分。

轻量级分支 ¶

如果您正在分阶段进行功能或错误修复，涉及多个提交，并且某些中间阶段不稳定到无法合并到主干，那么请在 /branches 中创建一个临时分支。无需询问——直接创建即可。在临时分支中尝试实验性想法也是可以的。所有上述内容适用于部分提交者和完整提交者。它甚至适用于其他 ASF 项目的提交者，但请与我们联系（在 dev@ 上）——介绍您自己以及您计划处理的问题。

完成分支后——无论是将其合并到主干还是放弃它——请记住将其删除。

另请参阅 关于部分提交访问权限的部分，了解我们关于为实验性分支提供提交访问权限的政策。

BRANCH-README 文件 ¶

对于您预期将长期存在的分支，我们建议在分支根目录中创建一个名为 BRANCH-README 的文件，并定期更新该文件。此类文件为您提供了一个绝佳的中心位置来描述分支的以下方面

• 分支的基本目的：它存在于修复哪个错误或实现哪个功能；它与哪些问题编号相关；哪些列表讨论线程围绕它；哪些设计文档存在于描述这种情况。

• 您正在使用哪种分支管理风格：这是一个功能分支，它将定期与父分支保持同步，并最终重新集成回该父分支？它是一个预计在可预见的将来不会合并回其父分支的分支？它是否与任何其他分支相关？

• 您在分支上还有哪些任务要完成？这些任务是否有人认领？他们是否需要更多设计输入？其他人如何帮助您？

这是一个示例 BRANCH-README 文件，演示了我们正在讨论的内容

This branch exists for the resolution of issue #8810, per the ideas
documented in /trunk/notes/frobnobbing-feature.txt.  It is a feature
branch, receiving regular sync merges from /trunk, and expected to be
reintegrated back thereto.

TODO:

  * compose regression tests        [DONE]
  * add frob identification logic   [STARTED (fitz)]
  * add nobbing bits                []

为什么大惊小怪？因为这个项目理想化了沟通和协作，理解后者更有可能发生在将前者作为重点的情况下。

只需记住，当您将分支合并回其源代码时，请删除 BRANCH-README 文件。

记录一切 ¶

每个函数，无论是公共的还是内部的，都必须以一个文档注释开头，描述函数的功能。文档应提及函数接收的每个参数、每个可能的返回值，以及（如果不明确）函数可能返回错误的条件。

对于内部文档，在文档字符串中将参数名称大写，即使在实际声明中它们不是大写，这样它们对人类读者来说更突出。

对于公共或半公共 API 函数，文档字符串应放在 .h 文件中声明函数的上方；否则，它应放在 .c 文件中函数定义的上方。

对于结构类型，请记录结构本身的每个成员。

对于实际的源代码，在内部记录每个函数的代码块，以便熟悉 Subversion 的人能够理解正在实现的算法。不要包含明显或过于冗长的文档；注释应该帮助理解代码，而不是阻碍它。

例如

  /*** How not to document.  Don't do this. ***/

  /* Make a foo object. */
  static foo_t *
  make_foo_object(arg1, arg2, apr_pool_t *pool)
  {
     /* Create a subpool. */
     apr_pool_t *subpool = svn_pool_create(pool);

     /* Allocate a foo object from the main pool */
     foo_t *foo = apr_palloc(pool, sizeof(*foo));
     ...
  }

相反，记录相当大的代码块，像这样

      /* Transmit the segment (if its within the scope of our concern). */
      SVN_ERR(maybe_crop_and_send_segment(segment, start_rev, end_rev,
                                          receiver, receiver_baton, subpool));

      /* If we've set CURRENT_REV to SVN_INVALID_REVNUM, we're done
         (and didn't ever reach END_REV).  */
      if (! SVN_IS_VALID_REVNUM(current_rev))
        break;

      /* If there's a gap in the history, we need to report as much
         (if the gap is within the scope of our concern). */
      if (segment->range_start - current_rev < 1)
        {
          svn_location_segment_t *gap_segment;
          gap_segment = apr_pcalloc(subpool, sizeof(*gap_segment));
          gap_segment->range_end = segment->range_start - 1;
          gap_segment->range_start = current_rev + 1;
          gap_segment->path = NULL;
          SVN_ERR(maybe_crop_and_send_segment(gap_segment, start_rev, end_rev,
                                              receiver, receiver_baton,
                                              subpool));
        }

阅读 Subversion 代码以了解文档在实践中的外观；特别是，请参阅 subversion/include/*.h 以获取 doxygen 示例。

公共 API 文档 ¶

我们使用 Doxygen 格式来记录公共接口。这意味着任何在公共头文件中出现的内容。生成的文档在 网站上发布，用于最新的和一些早期的 Subversion 源代码。

我们只使用一小部分可用的 doxygen 命令 来标记我们的源代码。在编写 doxygen 文档时，以下约定适用

• 使用完整的句子和函数的散文描述，在参数名称前加 @a，在类型和宏名称前加 @c。
• 使用 <tt>...</tt> 来显示多个单词，使用 @p 来显示打字机字体中的单个单词。
• 常量值，如 TRUE、FALSE 和 NULL 应全部大写。
• 当多个函数相关时，定义一个组名，并使用 @defgroup 和 @{...@} 将它们分组在一起。

有关命令的完整列表，请参阅 Doxygen 手册。

编写补丁 ¶

要获取最新源代码，请运行

svn checkout https://svn.apache.org/repos/asf/subversion/trunk/ svn-trunk

并按照 INSTALL 文件中的说明操作。（如果您没有 svn 客户端，请 下载源代码包。）

如果您的补丁实现了新功能或更改了大量代码，请记住先在 dev@ 邮件列表中讨论。（IRC 上的 #svn-dev 也是在邮件列表讨论之前（而不是代替）快速反馈的合适场所。如果您在 IRC 上提问，请等待一段时间以获得回复，因为并非所有人一直在线（尤其是在周末）。）这样社区就可以尽早表达对所提议功能或实现细节的担忧并提出改进建议——如果这些反馈越早提供（甚至在编写任何代码之前）而不是之后，对所有各方来说总是更好。

如果您对补丁有任何疑问，请随时在 IRC 或 dev@ 上提问。

提交补丁 ¶

将补丁邮件发送到 [email protected]，主题行以 [PATCH] 开头。这有助于我们的 补丁管理员 立即发现补丁。例如

   Subject: [PATCH] fix for rev printing bug in svn status

如果补丁解决了特定问题，请也包含问题编号：“[PATCH] issue #1729: ...”。对该特定问题感兴趣的开发人员将知道阅读邮件。

补丁提交应包含一个逻辑更改；请不要在一个提交中混合 N 个不相关的更改——而是发送 N 封单独的电子邮件。

使用 svn diff -x-p 从 Subversion 主干工作副本的顶部生成补丁。如果您要 diff 的文件不在版本控制之下，您可以使用 diff -u 达到相同的效果。

请在您的补丁中包含一个日志消息。一个好的日志消息有助于潜在的审阅者理解您补丁中的更改，并增加它被应用的可能性。您可以将日志消息放在电子邮件正文中，也可以放在补丁附件的顶部（见下文）。无论哪种方式，它都应遵循 编写日志消息 中给出的指南，并用三个方括号括起来，如下所示

   [[[
   Fix issue #1729: Don't crash because of a missing file.

   * subversion/libsvn_ra_ansible/get_editor.c
     (frobnicate_file): Check that file exists before frobnicating.
   ]]]

（方括号实际上不是日志消息的一部分，它们只是用来清楚地将日志消息与其周围的上下文区分开来。）

如果可能，请将补丁作为附件发送，其 mime 类型为 text/x-diff、text/x-patch 或 text/plain。大多数人的邮件阅读器可以内联显示这些内容，并且将补丁作为附件可以让它们方便地从消息中提取补丁。切勿以存档或压缩形式（例如，tar、gzip、zip、bzip2）发送补丁，因为这会阻止人们直接在他们的邮件阅读器中查看补丁。

如果您无法使用这些 MIME 类型之一附加补丁，或者补丁非常短，那么可以直接将其包含在邮件正文中。但请注意：某些邮件编辑器会通过在长行的中间插入不需要的换行符来修改内联补丁。如果您认为您的邮件软件可能会这样做，请使用附件。

如果补丁实现了新功能，请确保在邮件中完整描述该功能；如果补丁修复了错误，请详细描述错误并提供重现步骤。这些指南的例外情况是，当补丁解决问题数据库中的特定问题时，在这种情况下，只需在您的日志消息中引用问题编号，如 编写日志消息 中所述。

补丁经过几轮反馈和更改后才能应用是正常的。如果您的补丁没有立即被接受，不要灰心，这并不意味着您犯了错误，只是意味着有 *很多* 双眼睛在查看每个代码提交，很少有补丁不需要至少进行一点改进。在讨论了人们对您的补丁的反馈后，进行适当的更改并重新提交，等待下一轮反馈，然后重复此过程，直到某个提交者应用它。您可以在提交补丁之前，通过查看和应用项目的 编码规范 来避免一些迭代。

如果您一段时间没有收到回复，并且没有看到补丁被应用，这可能只是意味着人们真的很忙。继续重新发布，不要犹豫指出您仍在等待回复。您可以这样想，补丁管理是高度可并行的，我们需要您承担管理和编码的份额。每个补丁都需要有人来引导它完成整个过程，而最适合做这件事的人就是最初的提交者。