我们在 OpenStack 中广泛使用 git 来编写文档，以便我们可以“像对待代码一样对待文档”——我看到这种趋势在很多地方都很流行，尤其是在 Write the Docs 社区。
查看 2014 年在波特兰举行的 Write the Docs 活动的这些演讲：
在 OpenStack 中，我们的文档工作流程模仿了我们的代码协作。我们发布补丁供人们审查，我们互相审查补丁（类似于 GitHub 上的拉取请求），并且我们为每个文档补丁都进行了构建和测试自动化。我们的想法是，将 GitHub 拉取请求工作流程中存在的协作用于文档和代码。我们都负责大约 25 个 OpenStack 项目的相关且准确的文档，这些项目是用 Python 编写的，分布在 130 个 git 存储库中，因此让我们一起协作。我确实收到了来自刚开始使用这些类型工作流程的作者的问题，因此我想汇集我们发现的一些最佳实践，并找到更多。
您如何处理大量文档拉取请求？
OpenStack 是一个 流行的开源项目，因此文档需要能够扩展以适应大量的贡献和贡献者。我们有系统可以让我们每天合并多达 50 个文档补丁，尽管通常约为 15 个。由于 OpenStack 使用 Gerrit，因此我的一些技巧是针对该基于 Web 的团队软件代码审查工具，而不是 GitHub。但是，这些是指南，应该普遍适用。我还强烈推荐“项目所有者如何在 GitHub 上使用拉取请求”，其中提供了调查结果，并总结了集成者如何使用拉取请求作为补充阅读的主题。
我们使用以下工具和流程处理许多补丁请求（在 OpenStack 中，它们在技术上不是拉取请求）：
如果我遗漏了您最喜欢的助手，请在下面评论！
门禁测试：机器人助手
我们有“门禁测试”，可以自动化社区对任何贡献进行的大量初始质量检查。我们的门禁测试检查以下内容：
- “此补丁中的文档是否可以构建？”
- “所有已修补文件中的语法是否正确？”
- “所有链接是否都有效？”
- “该补丁是否删除了其他交付件使用的任何文件？”
必须通过这四项测试才能允许合并，因此它们是我们的真正门卫。为了进一步提高效率，这些测试仅在与补丁相关时才运行。因此，如果补丁中未删除任何文件，则不会运行删除测试。这节省了人们在本地引入补丁并手动运行测试的时间。还有其他测试会报告结果，但实际上并不会阻止补丁通过门禁，例如“翻译是否仍然可以与此补丁一起使用？” 文档的持续集成 (CI) 具有颠覆性。我认为我怎么强调这一点都不为过，但这篇文章的重点是扩展文档审查。如果您想了解有关 OpenStack 的 CI 系统的更多信息，请查看 ci.openstack.org。
技术准确性：人工检查员
测试补丁的技术准确性是耗时的部分，并且很难预测文档审查所需的时间。至关重要的是，人工要仔细检查对文档的任何贡献的技术准确性，我们在此处依赖我们的审阅者。设置允许您测试用户操作的环境是成为审阅者的一部分，并且可以节省您的时间。DevStack 是一组用于运行配置的开发环境的脚本，针对本地设置进行了调整。TryStack 是一个使用捐赠的硬件和资源运行的免费公共云。例如，如果我有一个基于 OpenStack 稳定分支的工作 DevStack 环境，我可以针对已知版本的 OpenStack 运行客户端命令。我可以拥有对我自己运行的 DevStack 环境的管理访问权限。我还有一个 TryStack 帐户，它通过 CLI 或 API 命令为我提供免费的云资源。我还有一个 Rackspace Cloud 帐户，可以让我测试 API 调用。
提交消息中的 Bug 链接
我们有一个快捷方式系统，允许贡献者在提交消息中放置诸如“Closes-bug:nnnnnn”之类的短语，其中 nnnnnn 来自 Launchpad 系统（我们的缺陷跟踪器）。文档错误和贡献本身之间的这种联系对于查看补丁是否解决了已记录错误的问题非常方便。我经常通过先点击进入错误，通读评论，然后查看补丁是否修复了损坏的内容来审查补丁。您还需要确保您的流程确保贡献者知道错误是否被接受为错误。在我们的系统中，必须将其设置为“已确认”。在 GitHub 中，您需要在问题上使用标签，并从您的拉取请求链接到该问题。
提交消息标准
在 OpenStack 中，我们一天可以合并多达 70 个补丁（仅用于文档），因此一致的提交消息使扫描更容易，以便找到您可以使用基本知识审查的补丁。看起来很挑剔，但是了解您一天可以查看 50 个补丁有助于您理解挑剔的理由。以下是我们标准的摘要：
- 在第一行中提供对更改的简要描述。
- 在第一行之后插入一个空行。
- 在以下行中提供对更改的详细描述，并在需要时断开段落。
- 第一行应限制为 50 个字符，并且不应以句点结尾（超过 72 个字符的提交消息将被门禁拒绝）。
- 后续行应在 72 个字符处换行。
约定
所有审阅者都知道我们使用一套针对 OpenStack 文档的约定，我们可以在审查补丁时指出这些约定。这组标准有助于我们检查服务命名的一致性、出于法律目的的大写以及诸如“无堆叠标题”之类的结构约定。我们在 OpenStack Wiki 上发布了这些标准，并且对它的任何更改都会在任何重大更改之前在 openstack-docs 邮件列表中讨论。当 Wiki 页面无法解决问题时，我们使用 IBM 风格指南作为我们在任何风格或约定问题上的最终仲裁者。
所有待审阅的仪表板
使用 Gerrit，我们可以对相关的补丁进行特定搜索以进行审查。例如，我创建了一个所有 OpenStack 文档存储库的仪表板（链接需要登录）。您还可以拥有一个仅用于影响 API 的补丁的仪表板。实际上，借助搜索功能，您可以定制仪表板以审查您想要的内容并按您的喜好确定优先级。
日历项，提醒您进行审查
由于我们的日历上有很多会议，因此最好留出时间进行审查。有时人们希望在工作日结束时或在第一件事时进行审查，以完成大量工作。真正重要的是由您来确定工作日中审查的优先级。我使用日历项作为提醒，并安排时间进行审查。
审查的预期周转时间是多少？
实际上，这取决于补丁或拉取请求的大小，以及有多少审阅者有足够的知识来审查该补丁。我们使用数据分析来衡量 OpenStack 中审查的周转时间。在过去五个月左右的时间里，我们对审查进行了以下类型的周转：
- 审查总数：2102 (每天 70.1 个)
- 审阅者总数：113 (每个审阅者每天 0.6 个)
- 核心团队审查总数：1570 (每天 52.3 个)
- 核心团队规模：21 (每个核心成员每天 2.5 个)
老实说，我们有一位审阅者（Andreas Jaeger）非常厉害，我们活跃的核心团队规模更像是 15 人而不是 21 人。在 OpenStack 中，核心审阅者是那些可以将内容发布到站点的人。任何人都可以审查文档补丁。我希望每天至少完成 2-10 次审查。在一个良好的审查周中，我可以完成大约 60 次审查。因此，我对我们的文档贡献者设定的期望是大约 3-5 天才能收到审阅者的评论，以便他们可以解决这些评论。
总结
作者可能不愿与他人合作交付成果，而开发人员可能觉得他们对文档几乎没有贡献。我认为没有人可以知道所有事情，因此像您在代码上协作一样，通过共同编写来分配工作量。我希望这些技巧可以帮助您将文档工作流程与 git 和 GitHub 工作流程相匹配，以便您可以加速您的协作编写，尤其是在开源中。
7 条评论