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 /openstack­doctools)，大部分使用Python撰寫。開發這些腳本的流程與文檔創建的工作流程是相同的。主要修改完成后，測試工具的一個發行版本之完成，并用于對文檔修改的測試。文檔庫使用test­requirments.txt 文件的Python慣例示意 openstack­doc­tools的哪個版本對應哪套文檔源文件。

自動測試將細究文檔的形態，使審閱者能夠專注于內容。盡管文檔無需通過全部自動測試，它必須通過被定義為“評分”的測試內容才可以被歸并及發布。另一部分測試內容被定義為“非評分”，指不是必須通過的測試內容。

#p#

一些自動測試的內容包括：

· 檢查獨立文件的語法，幫助查找語法錯誤，可用于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年。

原文鏈接：http://www.openstack.cn/?p=3743