如何幫助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 /openstack­doctools)，大部分使用Python撰寫。開發這些指令碼的流程與文件建立的工作流程是相同的。主要修改完成後，測試工具的一個發行版本之完成，並用於對文件修改的測試。文件庫使用test­requirments.txt 檔案的Python慣例示意 openstack­doc­tools的哪個版本對應哪套文件原始檔。

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

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

· 檢查獨立檔案的語法，幫助查詢語法錯誤，可用於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