持续集成和交付文档

您是否在不断地整合和交付文档方面陷入困境？阅读有关OpenStack如何对待文档（如代码）并实现成功合并和发布策略的知识，可能对您很有帮助。

在不到三个月的时间内，OpenStack如何合并900多个文档更改？我们将文档视为代码，并不断发布来自多个git存储库的审阅内容。

CI代表持续集成。通常，CI意味着要对代码进行持续测试，将其与其他代码更改集成在一起，然后合并。连续部署（CD）意味着代码与每个补丁一起连续部署到整个代码库。就文档而言，这意味着内容将被不断测试，与每个补丁合并并部署。对于文档而言，部署意味着发布。例如，部署文档意味着将输出文件复制到Web服务器，以供所有人查看。

CI / CD文档

只能使用Gerrit代码检查系统对任何OpenStack存储库（包括我们的文档存储库）进行更改。Gerrit是由OpenStack基础架构团队运行的另一种基于Web的审阅工具，用于代码协作和审阅。

基本的工作流程是，文档提供者签出文档存储库，对文档进行更改，在本地对其进行测试，将其提交至git（我们的源代码控制修订系统），然后将其上传至OpenStack的Gerrit实例。Gerrit然后向Jenkins发送通知，通知它有新的更改，Jenkins为软件开发提供了持续的集成服务。一旦来自Gerrit的通知通过，Jenkins将运行为存储库配置的各种测试套件。实际上，OpenStack并行运行八个Jenkins实例，并使用称为Zuul的自产工具进行协调。您可以在Zuul网站上查看任何给定版本的状态。

一旦将更改上传到Gerrit，审阅者就可以看到更改并开始对此进行评论。Gerrit的Web用户界面允许逐行查看更改。因此，审阅者可以直接对源文件中发现的任何问题发表评论。我们还实施了构建文档的测试，以便审阅者在适用时可以查看HTML或PDF格式的文档。

审核者对更改发表评论后，她也可以对更改进行投票。在这里投票不是一个民主的过程，而是对补丁程序应该加入的评估。审阅者可以投赞成票（是的，应该投赞成票）或投反对票（需要更多的工作），或者只发表评论和弃权。

修改过的openstack文档工作流程

每个人都可以通过以下投票在OpenStack的Gerrit中进行评论：

• 0：无分数

• +1：对我来说不错，但其他人必须批准

• -1：此补丁程序需要进一步的工作才能合并

我们还需要对补丁进行评论，说明其错误原因，需要澄清的问题或说明其正确性的原因。这些评论可帮助原始作者和其他审阅者更新和评估更改。

由高级审核员组成的特殊小组，即所谓的“核心审核员”，也可以进行+2（或-2）投票并批准一项更改，以便将其发布。这些评论通过以下任一方式指示：

• +2：对我看来不错（核心评论者）

• -2：不合并

一旦两个核心审阅者给了+2，一个核心审阅者（通常是第二个对变更给予+2的人）批准了变更，然后合并并发布。带有负面评论的更改不会获得批准，因此只有在达成共识并获得适当批准之前，文档才能发布。

詹金斯（Jenkins）进行的自动测试也导致了审核阶段的投票。变更获得批准后，Jenkins会再次运行测试（将变更与当时最新的git存储库合并），以确保不会出现任何退步。只有在Jenkins积极地检查变更后，变更才能合并。

所有这些自动更改都在HP和Rackspace公共云中运行。目前，OpenStack项目为此使用多达950个虚拟机。对于每项测试作业，都将启动一台计算机，在其中检出测试变更的存储库中，安装测试套件的所有依赖项，然后执行测试套件。是的，我们正在将云用于有关云的文档。

我们当前运行的测试在下面的部分中列出。

将CI / CD用于文档有什么好处？

OpenStack每天都有多个项目合并多个更改，因此文档系统还需要能够跟上这么多更改。持续的集成和部署可以实现这一点，因此这不仅对我们带来好处，而且对我们的环境是一项要求。作家具有与开发人员相同的工作流程，并获得与开发人员相同的认可和奖励。

我们还发现，尽管贡献者仍然需要能够在本地构建文档，但是它减轻了在本地编写者环境中构建文档的负担。通过准备好草稿供审阅，临时供稿人和审阅者可以避免下载补丁，复制构建环境以及构建文档的开销。由于系统的自动化，我们可以查看源和输出。

构建速度加快了，因为在基于云的CI / CD继续运行的同时，编写者可以一次处理多个补丁。在OpenStack中，基础架构团队还使用许多相同的技术来管理服务器。

由于使用了测试脚本，编写器始终从工作状态开始，而主分支始终在构建。如果文档不在本地或在其他环境中构建，那么作者可以确定这是他自己的错，而不是已经损坏的树。

草稿文档的构建和发布使审阅者可以快速检查更改在发布时如何呈现。他们不需要在本地下载和构建，因此可以更快地进行审核。

我们还使用了与OpenStack开发人员和基础架构团队相同的工作流，这使开发人员可以轻松地为文档做出贡献。随着我们最近转向RST作为格式，它变得更加容易，因为RST是OpenStack中使用的通用标记语言。

自动化风险和陷阱

考虑到写作既是一门艺术又是一门手工艺，因此我们确实尝试在应该自动进行的工作和仍然需要高级手工艺的工作之间取得平衡。早期的担忧是发布时间太早，或者发布的文档不完整。我们发现，只要审阅者有诸如“比现在更好的指南”或“我已经对其进行了测试并且知道它可以正常工作”或“此文档修复与我调查过的报告错误相匹配”之类的准则，那么每天发布50-100次更新的风险降低了。

我们必须在审稿人之间建立信任，并且在我们为期六个月的峰会上，我们仍然会就审稿进行现场讨论。我们编写了审阅指南 ，并试图培训审阅者在审阅补丁时如何使用最佳判断力。我们还编写了一套审核指南。持续集成不仅是我们发布速度的一部分，而且让值得信赖的审稿人使用良好的判断力，同时让机器人测试审阅使他们有信心，他们不必担心文档不会生成或我们会中断整个文档站点一夜之间。

我们有一些与发行版无关的手册以及记录当前发行版的手册。对于记录特定发行版的手册（如安装指南），我们为每个新发行版进行更新，并在分支机构中工作。已发布的文档进行了重要更改，而下一个版本的文档则进行了大部分更改，并发布在隐藏的位置，以方便查看当前草案。在软件发行版发布后，我们会公开发布这些特定于发行版的指南，然后开始为下一个发行版进行更新。

文件测试

Jenkins允许执行脚本，并且文档团队拥有自己的包含测试脚本的存储库，其中大多数是用Python编写的。我们使用与文档相同的工作流程来开发这些脚本。一旦进行了重大更改，就完成了测试工具的发布，然后将该版本用于测试任何文档更改。在文档存储库中，我们使用test-requirments.txt文件的Python约定，该约定指示哪个发行版的openstack-doc-tools与给定的一组文档源文件一起使用。

为了使审阅者可以专注于内容，而不必费力地选择表格，自动测试可以为我们处理大部分的选择。但是，我们并不需要通过所有自动测试才能发布文档。有些测试被标记为“投票”，这意味着除非通过所有这些测试，否则文档不会合并。其他测试被标记为“无投票权”，这意味着即使测试失败，我们也允许补丁着陆。自动测试是：

检查单个文件的语法。这有助于快速定位语法错误。可以针对DocBook XML，WADL XML，RST和JSON格式测试语法，但是我们仅测试DocBook XML和RST。在其他测试中，将检查JSON的格式是否正确。

检查文档是否生成。这样做的附带好处是，将生成的指南上载到草稿服务器，以便审阅者可以轻松地审阅新生成的书籍，并查看HTML和PDF中的更改外观。

检查翻译的手册是否贯穿整个工具链。

检查文件是否“不错”。这会根据文件类型（XML，RST或JSON）进行检查，检查是否存在多余的空格，超长行，某些不需要的unicode字符或正确的格式（JSON）。多余的空格和太长的行使得并排查看源文件更加困难。我们的工具链无法输出某些Unicode字符，并且JSON文件应符合格式标准。

检查到外部网站的链接是否有效。这将检查已更改的DocBook XML文件中的所有URL是否都可以访问。由于网站可能已关闭，此更改被标记为“无投票权”。

检查是否没有删除其他手册使用的XML文件。这很重要，因为我们只构建更改过的手册，因此，如果删除一个文件，我们必须检查所有手册仍然可以构建。

我们还对测试脚本进行了一些优化。例如，由于DocBook XML文件的构建成本很高，因此，小的依赖项构建器会检查哪些文件已更改以及哪些指南包括这些文件，然后仅构建那些指南。其他测试（例如语法或URL检查）也仅在更改后的文件上运行。没有理由一遍又一遍地检查未更改的文件，虽然测试单个文件可能很快，但是测试近一千个XML文件却很慢。

这些优化目前尚未在RST文件上完成，因为RST文件更容易解析，并且指南的构建也更快。

我们不会运行任何语法或拼写检查器，因为投票检查必须始终准确。关于自动进行拼写检查，我们进行了很多讨论，但这确实需要人眼来判断。

CI基础结构的其他用途

我们用它来与我们的翻译服务器对话。翻译团队使用翻译服务器（当前为Transifex）来翻译手册。每当合并更改时，CI基础结构都会自动将当前文本上载到翻译服务器，以便翻译人员可以直接翻译并始终拥有最新的字符串。每天一次，在CI基础架构上运行所谓的“定期”作业，以将所有翻译后的字符串从翻译服务器下载到文档存储库，然后建议对任何新字符串进行更改。这使我们有机会通过CI基础结构以及手动审核来运行翻译导入。

此外，我们使用CI基础结构将一些共享文件从一个存储库同步到另一些存储库。这些文件是我们共享的术语表和共享的“支持附录”及其翻译。将更改合并到这些文件的主存储库后，将检查其他存储库中的文件是否需要更新，如果是这种情况，则建议对该存储库进行更改。同样，这允许在导入时运行测试套件并进行最终的手动检查。

概要

希望本文为您提供有关我们如何在OpenStack文档过程中使用持续集成和部署的想法。我们发现，该方法带来的好处远大于任何风险。我们需要与其他团队进行比赛，这意味着我们采用了持续不断的心态，希望提早并经常发货。着眼于自动化，看一下您的开源文档，看看会出现什么。