OpenStack 文档的持续集成与持续交付是怎么实现的？

OpenStack 是如何做到在三个月内合并 900 个文档修改的？我们对待文档就像对待代码一样，并且持续公布了来自多个 Git 仓库的评估内容。

通常持续集成（CI）意味着代码被不断地测试，与其他的代码修改进行整合与合并。持续交付（CD）则意味着不断将带有补丁的代码部署到整个代码库中。在文档案例中，这意味着内容被不断地测试，不断合并每个补丁，并进行部署。对于文档来说，部署就意味着发布。部署文档意味着输出文件被拷贝到了 Web 服务器上供所有人查阅。

针对文档的 CI/CD

对包括文档仓库在内的任何 OpenStack 仓库的修改，只能够通过 Gerrit 代码评估系统完成。Gerrit 是一款由 OpenStack 基础设施团队运行、基于 Web 的评估工具，我们可以在代码协作和评估中使用它们。其基本的工作流是，文档捐献者检查文档仓库，修改文档，在本地测试它们，将其提交给 git——我们的源控制版本系统，然后将它们上传到 OpenStack 的 Gerrit 实例中。

Gerrit 随后发布通知，告之为软件开发提供持续性集成服务的 Jenkins 有了新的修改。一旦 Gerrit 发布了通知，Jenkins 将运行多种针对仓库配置的测试套件。实际上，OpenStack 并行运行着 8 个 Jenkins 实例，通过自产的名为 Zuul 的工具进行协调。在 Zuul 网站上，用户可以查看所有指定版本的状态。

只要修改被上传到 Gerrit 上，评估者就可以看到修改，并且对它们进行评论。Gerrit 的 Web 用户接口允许对修改进行逐行评估。因此，评估者能够对源文件中的任何问题进行直接评论。我们还会对构建文档展开测试，评估者可以适时地查看在 HTML 或 PDF 中构建的文档。一旦评估者对修改进行了评论，她还可以对修改进行投票。这里的投票并不是一个民主程序，它们更多的是用于评价补丁是否应该被采用。评估者可以投支持票（即应该被采用）或者是反对票（这需要做更多的工作），也可以仅发表评论，放弃投票。

每个人都可以通过这些投票在 OpenStack 的 Gerrit 中进行评估：

0：不计分；
+1：在我看来这很好，但是还需要其他人批准；
-1：在被合并之前这些补丁需要进一步完善；

我们还需要对补丁进行评论，阐明它们为什么是错误的，一些问题需要被澄清，或者是说明它们为什么很好。这些评论可以帮助原作者或其他评估者更新和评估这些修改。

高级评估者，即“核心评估者”（core reviewers）能够给予分值为 2 分的投票并批准修改，让该修改能够被发布。这些评估分值的含义是：

+2：在我看来（核心评估者）这很好。
-2：不能合并。

一旦两名核心评估者给了 +2（一名核心评估者赞同该修改，通常第二名核心评估者也给了 +2）那么它们就会被并入和被发布。带有负评论的修改是不会被批准的，在意见达成一致并通过批准后文档才能被发布。

在评估阶段，Jenkins 的自动检测也会进行一个投票。一旦修改被批准，Jenkins 会再次对并入当前升级后的 git 仓库的修改进行检测，以确保不会产生倒退。如果 Jenkins 对修改的评价是肯定的，那么修改仅仅是被并入。

这些自动化修改是在惠普和 Rackspace 的公有云上进行的。OpenStack 项目目前可使用 950 台虚拟机展开测试工作。每一项测试工作都会启动一台机器，所有与测试套件有关的东西都会被安装，然后测试套件会展开测试。是的，我们正在使用云来测试关于云的文档。

使用文档 CI/CD 会带来哪些好处？

OpenStack 每天都会将多个项目与多个修改进行合并，因此文档系统也需要能够跟上修改的步伐。持续集成与交付使得它成为了可能。这不仅是一个优势，也是我们环境所提出的需求。编写者的工作流与开发者的工作流相同，他们也得到了与提供捐献的开发者一样的认可与奖励。

我们还发现，尽管捐献者仍然需要能够在本地构建文档，但是它们正在让构建文档远离本地编写者的环境。通过让已经建立的草稿做好评估准备，临时捐献者和评估者可以避免过度下载补丁，过度复制构建环境，以及过度创建文档。我们之所以能够评估源和输出，应该感谢系统的自动化。

由于在基于云的 CI/CD 持续运行的同时，编写者能够迅速致力于多个补丁，因此构建速度得到了提升。在 OpenStack 中，基础设施团队也使用了许多针对服务器管理的技术。

草稿文档的创建和发布允许评估者在文档被发布时快速检查修改是如何被呈现出来的。他们不需要下载和在本地创建就能够快速地进行评估。

我们还使用了 OpenStack 开发者和基础设施团队所使用的工作流。对于开发者来说，他们可以更轻松地捐献文档。随着我们近期开始转而将 RST 作为格式，由于 RST 在 OpenStack 中已成为了标记语言，这些都变得更加容易了。

自动化中的风险与陷阱

考虑到编写既是一门技术也是一门艺术，我们一直在尝试着在自动化和手动之间实现一种平衡。一个早期的担忧是发布过快，或是发布不完整的文档。我们发现只要评估者采取的指导方针是“它们比我们现在的好”，“我对它们进行了测试，并知道它们是如何工作的”，或是“这个文档解决了我调查过的已经被上报的漏洞”，那么一天发布 50 至 100 次更新所隐藏的风险将会出现下降。

我们必须要在评估者中建立起信任，在每六个月召开一次的 OpenStack Summit 上，我们还将会展开现场讨论。我们已经编写了评估指南，并尝试着对评估者展开培训，让他们在评估补丁包时拥有最佳的判断力。

为此我们还缩写了一套评估指导。持续集成不仅是我们快速发布的一部分，也在促进值得信任的评估者展开最公正的评估。与此同时，让机器人进行测试评估会让他们相信自己不必担心文档无法被创建，或者是我们破坏了整个文档站点。

文档测试

Jenkins 允许执行脚本，文档团队拥有自己的测试脚本的仓库。这些测试脚本多数都是由 Python 编写的。我们使用与文档相同的工作流开发这些脚本。一旦进行了重大修改，我们就会编写一个测试工具版本，随后这个版本就会被用于测试所有的文档修改。在文档仓库中，我们会使用一个测试所需的.TXT 文件，这个文件会显示哪些 openstack- 文档 - 工具的版本能够与给定的系列源文件协同工作。

为了让评估者能够将关注点聚焦在内容上，而不是格式上，自动测试为我们处理了大部分挑错的工作。为了发布文档，我们不需要通过所有的自动测试。一些测试只是用于“投票”，这意味着文档不会进行合并，除非它们通过了所有的这些测试。部分测试是用于“非投票”，这意味着即便测试失败，我们也会允许发布补丁。

我们还对测试脚本进行了一些优化。例如，由于 DocBook XML 文件创建非常昂贵，一个小型的独立创建器可以用于检测哪些文件经过了修改，哪些指南中包括了这些文件，随后只有指南将被创建。如语法或 URL 检测等其他测试仅运行于经修改的文件。没有必要对那些没有经过修改的文件进行反复检测，测试单个文件可能会非常快，而测试上千个 XML 文件的速度就很慢了。

这些优化没有用于 RST 文件，因为 RST 文件非常容易分析，指南的创建也更为迅速。由于核对投票需要非常精准，因此我们也没运行语法和拼字检查器。我们已经就自动化拼写展开了充分讨论，不过这实际上还是需要人通过肉眼进行判断。

CI 基础设施的其他用途

我们会使用它们与我们的翻译服务器对话。翻译团队会使用 Transifex 翻译服务器翻译说明。只要修改被并入，那么 CI 基础设施就会自动将当前文本上传至翻译服务器，翻译者可以直接对它们进行翻译。每天 CI 基础设施会从翻译服务器定期下载所有的翻译好的内容到文档仓库。随后新的内容会作为修改被提出来。

此外，我们还使用 CI 基础设施将来自一个仓库的共享文件同步至其他仓库中。这些文件是我们与其他翻译共享的词汇表和“支持附件”。在修改被并入到这些文件的主仓库中，它们会检测其他仓库中的文件是否需要升级；如果需要，那么相关修改会被提出。这一过程允许在导入和最终的人工评估中运行测试工作套件。

结语

本文有助于我们理解如何在 OpenStack 文档处理流程中使用持续集成与持续交付。在这种方法中，我们会找到比风险更具价值的优势。在关注开源文档的同时关注自动化，看看哪些会让你突然感到眼前一亮吧！

本文编译自 opensource.com 网站，作者为 Anne Gentle，Gentle 女士一直在使用针对 API 设计与文档的开源技术，致力于与 Rackspace 的 OpenStack 项目相关的开源项目。编译者范范。InfoQ 经译者授权后发布，原译文链接。

感谢郭蕾对本文的审校。