CI(Continuous Integration)意為 “持續(xù)整合”，指代碼的持續(xù)測(cè)試及與其他代碼修改的整合與歸并。CD(Continuous Deployment)意為 “持續(xù)部署”，指代碼與其補(bǔ)丁的持續(xù)部署于整個(gè)代碼庫(kù)。拿文檔來看，就是內(nèi)容的持續(xù)測(cè)試、與必要修改的歸并及部署。在此，部署意為發(fā)布。舉例來說，“部署文檔”是指輸出文件被復(fù)制于web服務(wù)器為人閱覽。
文檔的持續(xù)整合與持續(xù)部署
任何OpenStack庫(kù)，包括文檔庫(kù)的修改只能通過Gerrit 代碼查核系統(tǒng)完成。Gerrit是由OpenStack基礎(chǔ)架構(gòu)團(tuán)隊(duì)運(yùn)營(yíng)管理的基于網(wǎng)頁(yè)的附加查核工具，用于代碼協(xié)作及審閱。其工作流程為：文檔貢獻(xiàn)者在文檔庫(kù)中核對(duì)文檔，做出修改，在本地測(cè)試，提交至git – 資源管理及修訂系統(tǒng)，后上傳至OpenStack的Gerrit事例。Gerrit將修改通知到為軟件開發(fā)提供持續(xù)整合服務(wù)的Jenkins。Jenkins收到通知后，將運(yùn)行為該庫(kù)配置好的測(cè)試包。目前，OpenStack有八個(gè)并行的Jenkins事例，由自主開發(fā)的工具Zuul協(xié)調(diào) (http://status.openstack.org/zuul/)。
任何人都可以在OpenStack的Gerrit成為審閱者
0: 無分?jǐn)?shù)。
+1: 我覺得可以通過，但需要他人同意。
1: 該修改還需完善，以成為可歸并的補(bǔ)丁。
補(bǔ)丁本身同樣需要評(píng)議來闡述其必需性、尋求附加說明，或?qū)ρa(bǔ)丁作出肯定。
資歷較深的“核心審閱者”可為修改做出“+2”或“-2”的評(píng)分，以決定修改可否成為修補(bǔ)并發(fā)布：
+2: 同意(核心審核人)
2: 不同意
被兩位核心審閱者評(píng)以“+2”的修改將通過審核，被歸并、發(fā)布。得負(fù)分的修改不會(huì)被批準(zhǔn)，相關(guān)文檔在達(dá)到共識(shí)之前也不會(huì)被發(fā)布。
Jenkins的自動(dòng)測(cè)試也可在審閱過程中形成評(píng)分。
當(dāng)修改被批準(zhǔn)后，Jenkins將對(duì)已與該修改歸并，更新后的git 庫(kù)進(jìn)行測(cè)試，確保避免出現(xiàn)復(fù)歸。修改只有被Jenkins審核通過后才可以被歸并。
以上所有自動(dòng)更改都可運(yùn)行于HP和Rackspace公有云。目前，OpenStack項(xiàng)目為此目的運(yùn)行的虛擬機(jī)已達(dá)到950臺(tái)，每項(xiàng)測(cè)試工作對(duì)應(yīng)一臺(tái)機(jī)器，檢驗(yàn)被測(cè)試的修改所在的庫(kù)，安裝測(cè)試包所需組件并運(yùn)行測(cè)試包 是的，OpenStack正在用云來管理自身云的相關(guān)文檔。
下面的章節(jié)中將列出OpenStack目前正在運(yùn)行的測(cè)試。
持續(xù)集成與持續(xù)部署借鑒于文檔的優(yōu)勢(shì)何在?
每天都有多個(gè)OpenStack項(xiàng)目與多個(gè)修改歸并，而文檔系統(tǒng)與之同步的能力是必要的。持續(xù)集成與持續(xù)部署讓其得以實(shí)現(xiàn) – 這在當(dāng)下的環(huán)境中是必需的，而非僅是優(yōu)勢(shì)。作者與開發(fā)者的工作流程相同，會(huì)得到相同的認(rèn)可、獎(jiǎng)勵(lì)。
這套流程讓創(chuàng)建文檔不再是本地作者的負(fù)擔(dān)，盡管貢獻(xiàn)者仍需在本地建立文檔。可修改、審閱就緒的擬定文檔讓貢獻(xiàn)者避免了下載補(bǔ)丁、復(fù)制創(chuàng)建環(huán)境、再建立文檔的繁復(fù)流程，實(shí)現(xiàn)同時(shí)閱覽原始文件和輸出文件。
創(chuàng)建文檔的速度也會(huì)提高，因?yàn)樽髡呖稍贑I/CD運(yùn)行的同時(shí)完善多個(gè)修補(bǔ)。OpenStack的基礎(chǔ)架構(gòu)團(tuán)隊(duì)已將類似技術(shù)用于服務(wù)器管理。
由于測(cè)試腳本的限定，作者會(huì)一直以工作狀態(tài)為起始，逐漸完善所建文檔的各個(gè)分支。如文檔不能在本地或者其他環(huán)境創(chuàng)建，作者可以確定是自身問題，而非文檔分支的中斷。
擬定文檔的創(chuàng)建和發(fā)布將使審閱者能夠快速了解一項(xiàng)修改的實(shí)施效果，而無需下載并在本地建立，從而更快速的完成審閱。
這與OpenStack開發(fā)者與基礎(chǔ)架構(gòu)團(tuán)隊(duì)使用的工作流程相同，開發(fā)者們可以更輕松的成為文檔貢獻(xiàn)者。而近期向RST格式的轉(zhuǎn)變更是將這個(gè)優(yōu)勢(shì)強(qiáng)化：RST是OpenStack的常用審定語言。
自動(dòng)化的風(fēng)險(xiǎn)與陷阱
鑒于文檔撰寫本身的特性，OpenStack一直在嘗試平衡自主創(chuàng)建與人為修飾。一些早期疑慮包括過急的發(fā)布與不完整文檔的發(fā)布。我們發(fā)現(xiàn)，只要審閱者能夠以一項(xiàng)修改可否解決自己在實(shí)踐中遇到的問題作為該修改可否通過的評(píng)定標(biāo)準(zhǔn)，那么更新發(fā)布過于頻繁的風(fēng)險(xiǎn)就會(huì)降低。
盡管審閱者之間相互信任，大家依舊會(huì)在每半年舉行一次的峰會(huì)上相聚，就需審閱的文檔展開討論。一些詳盡的審閱指南已發(fā)布(詳見https://wiki.openstack.org/wiki/Documentation/ReviewGuidelines);有關(guān)如何高效判斷修補(bǔ)質(zhì)量的培訓(xùn)也在持續(xù)進(jìn)行。以機(jī)器測(cè)試結(jié)果為支撐，來自可靠的審閱者的正確判斷與持續(xù)整合同為發(fā)布速度的決定因素。
所述指南由兩部分組成：獨(dú)立于版本的內(nèi)容以及關(guān)于最新版本的內(nèi)容。基于某一版本制訂的指南，例如安裝說明，會(huì)跟隨每個(gè)新版本而更新。已發(fā)布的文檔會(huì)根據(jù)關(guān)鍵修改而更新，為下一版本準(zhǔn)備的文檔將被大幅修改并隱藏于現(xiàn)有擬定版文檔，以便當(dāng)前擬定版本的審閱。在新的軟件版本發(fā)行后，與之對(duì)應(yīng)的指南將被發(fā)布。之后，下一個(gè)版本的指南更新工作將展開。
文檔測(cè)試
Jenkins 可執(zhí)行腳本，文檔團(tuán)隊(duì)也擁有自己的測(cè)試腳本庫(kù) (https://github.com/openstack /openstackdoctools)，大部分使用Python撰寫。開發(fā)這些腳本的流程與文檔創(chuàng)建的工作流程是相同的。主要修改完成后，測(cè)試工具的一個(gè)發(fā)行版本之完成，并用于對(duì)文檔修改的測(cè)試。文檔庫(kù)使用testrequirments.txt 文件的Python慣例示意 openstackdoctools的哪個(gè)版本對(duì)應(yīng)哪套文檔源文件。
自動(dòng)測(cè)試將細(xì)究文檔的形態(tài)，使審閱者能夠?qū)Ｗ⒂趦?nèi)容。盡管文檔無需通過全部自動(dòng)測(cè)試，它必須通過被定義為“評(píng)分”的測(cè)試內(nèi)容才可以被歸并及發(fā)布。另一部分測(cè)試內(nèi)容被定義為“非評(píng)分”，指不是必須通過的測(cè)試內(nèi)容。
[page]一些自動(dòng)測(cè)試的內(nèi)容包括：
·檢查獨(dú)立文件的語法，幫助查找語法錯(cuò)誤，可用于DocBook XML, WADL XML, RST, 以及 JSON格式。在此我們只對(duì)DocBook XML 和 RST執(zhí)行此測(cè)試。對(duì)于JSON的格式檢查另有其他測(cè)試完成。
·檢查文檔的創(chuàng)建。它的附加價(jià)值在于新生成的指南將被上傳至擬定文檔服務(wù)器，方便審閱者在HTML和PDF格式中查閱。
·檢查指南譯本通過工具鏈創(chuàng)建。
·檢查文件精致度：根據(jù)不同的文件格式(XML, RST, 或JSON)檢查文檔格式、留白是否恰當(dāng)、字符是否統(tǒng)一、影響查閱源文件的諸多細(xì)節(jié)等。我們的工具鏈無法輸出一些統(tǒng)碼，且JSON文件需符合格式標(biāo)準(zhǔn)。
·檢查網(wǎng)頁(yè)鏈接是否可用，確保DocBook XML格式文件里的URL全部有效。鑒于一些網(wǎng)站本身可能失效，這項(xiàng)為“非評(píng)分”測(cè)試。
·檢查用于其他指南的XML 文件沒有被刪除。這項(xiàng)的重要性在于我們只創(chuàng)建修改的指南，因此需確保單一文件的刪除不會(huì)影響文檔的創(chuàng)建。
OpenStack也對(duì)測(cè)試腳本中完成了優(yōu)化。例如，鑒于創(chuàng)建DocBook XML文件是貴重的，小型的關(guān)聯(lián)創(chuàng)建工具可查看哪些文件被修改、被哪些指南涵蓋，從而只創(chuàng)建相關(guān)指南。其他測(cè)試，例如語法或URL測(cè)試同樣也只在有修改的文件執(zhí)行，而無需檢查沒有修改的文件 –相比測(cè)試單個(gè)文件，對(duì)近千個(gè) XML文件進(jìn)行檢查會(huì)略顯遲緩。
這些優(yōu)化未在RST文件完成，鑒于RST文件更易于解析，據(jù)此創(chuàng)建文檔也更快速。
鑒于評(píng)分機(jī)制所需的準(zhǔn)確性，我們不會(huì)對(duì)文字語法或拼寫創(chuàng)建測(cè)試。關(guān)于這個(gè)話題的討論有過很多，但的確，這是一項(xiàng)需要人為判斷的工作。
持續(xù)整合架構(gòu)的其他用途
持續(xù)整合架構(gòu)曾出現(xiàn)在翻譯服務(wù)器的討論中。目前，轉(zhuǎn)譯服務(wù)器“Transifex”被用于指南的翻譯工作。當(dāng)有修改被歸并時(shí)，持續(xù)整合架構(gòu)將當(dāng)前文字上傳至轉(zhuǎn)譯服務(wù)器，方便譯員直接將文字轉(zhuǎn)譯并一直擁有最新的字列。每天一次，一個(gè)所謂的“周期性”工作被運(yùn)行于持續(xù)整合架構(gòu)，下載全部完成轉(zhuǎn)譯的字列至文檔庫(kù)。之后，對(duì)于其他字列的修改被提出。這一機(jī)制讓我們得以將導(dǎo)入的轉(zhuǎn)譯與指南審閱一起通過持續(xù)整合架構(gòu)運(yùn)行。
此外，持續(xù)整合架構(gòu)也被用于分享文件在庫(kù)之間的同步。這些是共享的專業(yè)術(shù)語列表以及同用于其他轉(zhuǎn)譯的附錄。修改被歸并于這些文件的主庫(kù)后，系統(tǒng)將檢查其他庫(kù)中的文件是否也需更新。如有需要，對(duì)其他庫(kù)的修改將被直接通過。這樣，測(cè)試包被運(yùn)行于轉(zhuǎn)譯內(nèi)容，同時(shí)再次確認(rèn)指南的內(nèi)容無誤。
總結(jié)
本文旨在幫助讀者了解我們?nèi)绾螌penStack文檔編制與持續(xù)整合以及持續(xù)部署技術(shù)相結(jié)合。我們發(fā)現(xiàn)，這樣結(jié)合的利遠(yuǎn)大于弊。我們需要與其他團(tuán)隊(duì)相符，進(jìn)而需要盡早、盡量頻繁的發(fā)布。用自動(dòng)化的視角看看你的開源文檔，巧妙之處自會(huì)顯現(xiàn)。
原文由Anne 與Andreas Jaeger共同撰寫。Anne 與 Andreas同為OpenStack文檔團(tuán)隊(duì)成員。Andreas 曾就職于SUSE，對(duì)OpenStack持續(xù)整合架構(gòu)有深入研究，為不同的開源項(xiàng)目貢獻(xiàn)超過20年。
京公網(wǎng)安備 11010502049343號(hào)