Git 和 GitHub 用于开源文档

图片来源：

Flickr 用户：theaucitron (CC BY-SA 2.0)

我们在 OpenStack 中广泛使用 git 来进行文档编写，以便我们可以“像对待代码一样对待文档”——我看到这种趋势在很多地方流行，尤其是在 Write the Docs 社区中。

查看 2014 年在波特兰举行的 Write the Docs 大会的这些演讲

在 OpenStack 中，我们的文档工作流程模仿了我们的代码协作。我们发布补丁供人们审查，我们互相审查彼此的补丁（类似于 GitHub 上的 pull request），并且我们为每个文档补丁都进行了构建和测试自动化。我们的想法是，将 GitHub pull request 工作流程中存在的协作用于文档和代码。我们都负责大约 25 个 OpenStack 项目的相关且准确的文档，这些项目是用 Python 编写的，分布在 130 个 git 仓库中，所以让我们一起协作。我确实会收到一些刚开始使用这些类型工作流程的作者的提问，所以我希望汇集我们发现的一些最佳实践，并找到更多实践。

你如何处理大量的文档 pull request？

OpenStack 是一个流行的开源项目，因此文档需要扩展以适应大量的贡献和贡献者。我们有系统可以让我们每天合并多达 50 个文档补丁，尽管通常约为 15 个。由于 OpenStack 使用 Gerrit，因此我的一些技巧是专门针对该基于 Web 的团队软件代码审查工具，而不是 GitHub。但是，这些是应普遍适用的指南。我还强烈推荐“项目所有者如何在 GitHub 上使用 pull request”，其中提供了调查结果，并提取了集成商如何使用 pull request 的主题作为补充阅读。

我们使用以下工具和流程处理许多补丁请求（在 OpenStack 中，它们在技术上不是 pull request）

Gate 测试：机器人助手
技术准确性：人工检查员
commit 消息中的 Bug 链接
Commit 消息标准
约定
所有未完成审查的仪表板
日历项，用于提醒和安排时间

如果我遗漏了您最喜欢的助手，请在下面评论！

Gate 测试：机器人助手

我们有“gate 测试”，可以自动化我们社区所做的任何贡献的许多初始质量检查。我们的 gate 测试检查以下内容

“此补丁中的文档是否可以构建？”
“所有已修补文件中的语法是否正确？”
“所有链接是否都有效？”
“此补丁是否删除了任何其他交付件使用的文件？”

这四个测试必须通过才能允许合并，因此它们是我们的真正门卫。为了进一步提高效率，这些测试仅在与补丁相关时才运行。因此，如果在补丁中未删除任何文件，则不会运行删除测试。这节省了人工在本地获取补丁并手动运行测试的时间。还有其他测试会报告结果，但实际上并不会阻止补丁通过 gate，例如“此补丁的翻译是否仍然有效？” 文档的持续集成 (CI) 正在改变游戏规则。我认为我再怎么强调这一点也不为过，但这篇文章的重点是扩展文档审查。如果您想了解更多关于 OpenStack 的 CI 系统的信息，请访问 ci.openstack.org。

技术准确性：人工检查员

测试补丁的技术准确性是耗时的部分，并且很难预测文档审查需要花费多少时间。人工仔细检查对文档的任何贡献的技术准确性至关重要，我们在此依赖于我们的审查员。设置允许您测试用户操作的环境是成为审查员的一部分，并且可以节省您的时间。DevStack 是一组用于运行配置的开发环境的脚本集合，针对本地设置进行了调整。TryStack 是一个使用捐赠的硬件和资源运行的免费公共云。例如，如果我有一个基于 OpenStack 稳定分支的 DevStack 工作环境，我可以针对已知版本的 OpenStack 运行客户端命令。我可以拥有对我自己运行的 DevStack 环境的管理访问权限。我还有一个 TryStack 帐户，它通过 CLI 或 API 命令为我提供免费的云资源。我还有一个 Rackspace Cloud 帐户，可以让我测试 API 调用。

commit 消息中的 Bug 链接

我们有一个快捷方式系统，允许贡献者在 commit 消息中放置诸如“Closes-bug:nnnnnn”之类的短语，其中 nnnnnn 来自 Launchpad 系统（我们的 bug 跟踪器）。文档 bug 和贡献本身之间的这种联系对于查看补丁是否解决了已记录 bug 的问题非常方便。我通常会通过先点击进入 bug、阅读评论，然后查看补丁是否修复了损坏的内容来审查补丁。您还需要确保您的流程确保贡献者知道 bug 是否被接受为 bug。在我们的系统中，它必须设置为“已确认”。在 GitHub 中，您需要在问题上使用标签，并从您的 pull request 链接到该问题。

Commit 消息标准

在 OpenStack 中，我们一天可以合并多达 70 个补丁（仅用于文档），因此一致的 commit 消息使扫描更容易，以便找到您可以使用您的基本知识审查的补丁。看起来很挑剔，但是了解您一天可以查看 50 个补丁有助于您理解挑剔的理由。以下是我们标准的摘要

在第一行提供更改的简要描述。
在第一行之后插入一个空行。
在以下行中提供更改的详细描述，并在需要时分段。
第一行应限制为 50 个字符，并且不应以句点结尾（超过 72 个字符的 commit 消息将被 gate 拒绝）。
后续行应在 72 个字符处换行。

约定

所有审查员都知道我们为 OpenStack 文档使用了一套商定的约定，并且在审查补丁时可以指向这些约定。这套标准帮助我们检查服务命名的一致性、出于法律目的的大小写以及结构约定，例如“无堆叠标题”。我们将这些发布在 OpenStack wiki 上，并且对其的任何更改都会在任何重大更改之前在 openstack-docs 邮件列表中讨论。当 wiki 页面无法解决问题时，我们使用 IBM Style Guide 作为我们在任何样式或约定问题上的最终仲裁者。

所有未完成审查的仪表板

使用 Gerrit，我们可以对要审查的相关补丁进行特定搜索。例如，我创建了一个用于所有 OpenStack 文档存储库的仪表板（链接需要登录）。您还可以拥有一个仅用于影响 API 的补丁的仪表板。实际上，使用搜索功能，您可以定制您的仪表板以审查您想要的内容并根据您的喜好进行优先级排序。

日历项，用于提醒您进行审查

由于我们的日历上有很多会议，因此最好留出时间进行审查。有时人们希望在工作日结束时或第一时间进行审查，以完成大量工作。这实际上取决于您在工作日中优先考虑审查的程度。我使用日历项作为提醒，并留出时间进行审查。

审查的预期周转时间是多少？

实际上，这取决于补丁或 pull request 的大小，以及足够了解以审查该补丁的审查员数量。我们使用数据分析来衡量我们在 OpenStack 中审查的周转时间。在过去的五个月左右，我们在审查中进行了以下类型的周转。

审查总数：2102（每天 70.1 个）
审查员总数：113（每位审查员每天 0.6 个）
核心团队的审查总数：1570（每天 52.3 个）
核心团队规模：21（每个核心成员每天 2.5 个）

老实说，我们有一位审查员（Andreas Jaeger）非常厉害，而我们的活跃核心团队规模更像是 15 人而不是 21 人。在 OpenStack 中，核心审查员是那些可以将内容发布到网站的人。任何人都可以审查文档补丁。我希望每天至少完成 2-10 次审查。在一个好的审查周里，我可以完成大约 60 次审查。因此，我对我们的文档贡献者设定的期望是大约 3-5 天可以收到审查员的评论，以便他们可以解决。