如何帮助OpenStack开发者成为贡献者
CI(Continuous Integration)意为 “持续整合”，指代码的持续测试及与其他代码修改的整合与归并。CD(Continuous Deployment)意为 “持续部署”，指代码与其补丁的持续部署于整个代码库。拿文档来看，就是内容的持续测试、与必要修改的归并及部署。在此，部署意为发布。举例来说，“部署文档”是指输出文件被复制于web服务器为人阅览。
文档的持续整合与持续部署
任何OpenStack库，包括文档库的修改只能通过Gerrit 代码查核系统完成。Gerrit是由OpenStack基础架构团队运营管理的基于网页的附加查核工具，用于代码协作及审阅。其工作流程为：文档贡献者在文档库中核对文档，做出修改，在本地测试，提交至git – 资源管理及修订系统，后上传至OpenStack的Gerrit事例。Gerrit将修改通知到为软件开发提供持续整合服务的Jenkins。Jenkins收到通知后，将运行为该库配置好的测试包。目前，OpenStack有八个并行的Jenkins事例，由自主开发的工具Zuul协调 (http://status.openstack.org/zuul/)。
任何人都可以在OpenStack的Gerrit成为审阅者
- 0: 无分数。
- +1: 我觉得可以通过，但需要他人同意。
- 1: 该修改还需完善，以成为可归并的补丁。
补丁本身同样需要评议来阐述其必需性、寻求附加说明，或对补丁作出肯定。
资历较深的“核心审阅者”可为修改做出“+2”或“-2”的评分，以决定修改可否成为修补并发布：
- +2: 同意(核心审核人)
- 2: 不同意
被两位核心审阅者评以“+2”的修改将通过审核，被归并、发布。得负分的修改不会被批准，相关文档在达到共识之前也不会被发布。
Jenkins的自动测试也可在审阅过程中形成评分。
当修改被批准后，Jenkins将对已与该修改归并，更新后的git 库进行测试，确保避免出现复归。修改只有被Jenkins审核通过后才可以被归并。
以上所有自动更改都可运行于HP和Rackspace公有云。目前，OpenStack项目为此目的运行的虚拟机已达到950台，每项测试工作对应一台机器，检验被测试的修改所在的库，安装测试包所需组件并运行测试包 是的，OpenStack正在用云来管理自身云的相关文档。
下面的章节中将列出OpenStack目前正在运行的测试。
持续集成与持续部署借鉴于文档的优势何在?
每天都有多个OpenStack项目与多个修改归并，而文档系统与之同步的能力是必要的。持续集成与持续部署让其得以实现 – 这在当下的环境中是必需的，而非仅是优势。作者与开发者的工作流程相同，会得到相同的认可、奖励。
这套流程让创建文档不再是本地作者的负担，尽管贡献者仍需在本地建立文档。可修改、审阅就绪的拟定文档让贡献者避免了下载补丁、复制创建环境、再建立文档的繁复流程，实现同时阅览原始文件和输出文件。
创建文档的速度也会提高，因为作者可在CI/CD运行的同时完善多个修补。OpenStack的基础架构团队已将类似技术用于服务器管理。
由于测试脚本的限定，作者会一直以工作状态为起始，逐渐完善所建文档的各个分支。如文档不能在本地或者其他环境创建，作者可以确定是自身问题，而非文档分支的中断。
拟定文档的创建和发布将使审阅者能够快速了解一项修改的实施效果，而无需下载并在本地建立，从而更快速的完成审阅。
这与OpenStack开发者与基础架构团队使用的工作流程相同，开发者们可以更轻松的成为文档贡献者。而近期向RST格式的转变更是将这个优势强化：RST是OpenStack的常用审定语言。
自动化的风险与陷阱
鉴于文档撰写本身的特性，OpenStack一直在尝试平衡自主创建与人为修饰。一些早期疑虑包括过急的发布与不完整文档的发布。我们发现，只要审阅者能够以一项修改可否解决自己在实践中遇到的问题作为该修改可否通过的评定标准，那么更新发布过于频繁的风险就会降低。
尽管审阅者之间相互信任，大家依旧会在每半年举行一次的峰会上相聚，就需审阅的文档展开讨论。一些详尽的审阅指南已发布(详见https://wiki.openstack.org/wiki/Documentation/ReviewGuidelines);有关如何高效判断修补质量的培训也在持续进行。以机器测试结果为支撑，来自可靠的审阅者的正确判断与持续整合同为发布速度的决定因素。
所述指南由两部分组成：独立于版本的内容以及关于最新版本的内容。基于某一版本制订的指南，例如安装说明，会跟随每个新版本而更新。已发布的文档会根据关键修改而更新，为下一版本准备的文档将被大幅修改并隐藏于现有拟定版文档，以便当前拟定版本的审阅。在新的软件版本发行后，与之对应的指南将被发布。之后，下一个版本的指南更新工作将展开。
文档测试
Jenkins 可执行脚本，文档团队也拥有自己的测试脚本库 (https://github.com/openstack /openstackdoctools)，大部分使用Python撰写。开发这些脚本的流程与文档创建的工作流程是相同的。主要修改完成后，测试工具的一个发行版本之完成，并用于对文档修改的测试。文档库使用testrequirments.txt 文件的Python惯例示意 openstackdoctools的哪个版本对应哪套文档源文件。
自动测试将细究文档的形态，使审阅者能够专注于内容。尽管文档无需通过全部自动测试，它必须通过被定义为“评分”的测试内容才可以被归并及发布。另一部分测试内容被定义为“非评分”，指不是必须通过的测试内容。
一些自动测试的内容包括：
· 检查独立文件的语法，帮助查找语法错误，可用于DocBook XML, WADL XML, RST, 以及 JSON格式。在此我们只对DocBook XML 和 RST执行此测试。对于JSON的格式检查另有其他测试完成。
· 检查文档的创建。它的附加价值在于新生成的指南将被上传至拟定文档服务器，方便审阅者在HTML和PDF格式中查阅。
· 检查指南译本通过工具链创建。
· 检查文件精致度：根据不同的文件格式(XML, RST, 或JSON)检查文档格式、留白是否恰当、字符是否统一、影响查阅源文件的诸多细节等。我们的工具链无法输出一些统码，且JSON文件需符合格式标准。
· 检查网页链接是否可用，确保DocBook XML格式文件里的URL全部有效。鉴于一些网站本身可能失效，这项为“非评分”测试。
· 检查用于其他指南的XML 文件没有被删除。这项的重要性在于我们只创建修改的指南，因此需确保单一文件的删除不会影响文档的创建。
OpenStack也对测试脚本中完成了优化。例如，鉴于创建DocBook XML文件是贵重的，小型的关联创建工具可查看哪些文件被修改、被哪些指南涵盖，从而只创建相关指南。其他测试，例如语法或URL测试同样也只在有修改的文件执行，而无需检查没有修改的文件 –相比测试单个文件，对近千个 XML文件进行检查会略显迟缓。
这些优化未在RST文件完成，鉴于RST文件更易于解析，据此创建文档也更快速。
鉴于评分机制所需的准确性，我们不会对文字语法或拼写创建测试。关于这个话题的讨论有过很多，但的确，这是一项需要人为判断的工作。
持续整合架构的其他用途
持续整合架构曾出现在翻译服务器的讨论中。目前，转译服务器“Transifex”被用于指南的翻译工作。当有修改被归并时，持续整合架构将当前文字上传至转译服务器，方便译员直接将文字转译并一直拥有最新的字列。每天一次，一个所谓的“周期性”工作被运行于持续整合架构，下载全部完成转译的字列至文档库。之后，对于其他字列的修改被提出。这一机制让我们得以将导入的转译与指南审阅一起通过持续整合架构运行。
此外，持续整合架构也被用于分享文件在库之间的同步。这些是共享的专业术语列表以及同用于其他转译的附录。修改被归并于这些文件的主库后，系统将检查其他库中的文件是否也需更新。如有需要，对其他库的修改将被直接通过。这样，测试包被运行于转译内容，同时再次确认指南的内容无误。
总结
本文旨在帮助读者了解我们如何将OpenStack文档编制与持续整合以及持续部署技术相结合。我们发现，这样结合的利远大于弊。我们需要与其他团队相符，进而需要尽早、尽量频繁的发布。用自动化的视角看看你的开源文档，巧妙之处自会显现。
原文由Anne 与Andreas Jaeger共同撰写。Anne 与 Andreas同为OpenStack文档团队成员。Andreas 曾就职于SUSE，对OpenStack持续整合架构有深入研究，为不同的开源项目贡献超过20年。
本文作者：佚名
来源：51CTO
