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

[[141678]]

原文编者的话：

本文节选编译自opensource.com网站，作者为Anne Gentle。Gentle女士一直在使用针对API设计与文档的开源技术，致力于与Rackspace的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中进行评估：

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

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

#p#

使用文档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文档处理流程中使用持续集成与持续交付。在这种方法中，我们会找到比风险更具价值的优势。在关注开源文档的同时关注自动化，看看哪些会让你突然感到眼前一亮吧!

[[141679]]

本文作者Anne Gentle女士一直在使用针对API设计与文档的开源技术，致力于与Rackspace的OpenStack项目相关的开源项目。她确保了docs.openstack.org网站包括了横跨130git仓库，用Python编写的20个项目的相关文件和准确文件。她主张云用户和管理者提供准确的技术信息，以增加OpenStack部署。