您是否在不斷地整合和交付文檔方面陷入困境？閱讀有關(guān)OpenStack如何對(duì)待文檔（如代碼）并實(shí)現(xiàn)成功合并和發(fā)布策略的知識(shí)，可能對(duì)您很有幫助。

在不到三個(gè)月的時(shí)間內(nèi)，OpenStack如何合并900多個(gè)文檔更改？我們將文檔視為代碼，并不斷發(fā)布來自多個(gè)git存儲(chǔ)庫的審閱內(nèi)容。

CI代表持續(xù)集成。通常，CI意味著要對(duì)代碼進(jìn)行持續(xù)測(cè)試，將其與其他代碼更改集成在一起，然后合并。連續(xù)部署（CD）意味著代碼與每個(gè)補(bǔ)丁一起連續(xù)部署到整個(gè)代碼庫。就文檔而言，這意味著內(nèi)容將被不斷測(cè)試，與每個(gè)補(bǔ)丁合并并部署。對(duì)于文檔而言，部署意味著發(fā)布。例如，部署文檔意味著將輸出文件復(fù)制到Web服務(wù)器，以供所有人查看。

CI / CD文檔

只能使用Gerrit代碼檢查系統(tǒng)對(duì)任何OpenStack存儲(chǔ)庫（包括我們的文檔存儲(chǔ)庫）進(jìn)行更改。Gerrit是由OpenStack基礎(chǔ)架構(gòu)團(tuán)隊(duì)運(yùn)行的另一種基于Web的審閱工具，用于代碼協(xié)作和審閱。

基本的工作流程是，文檔提供者簽出文檔存儲(chǔ)庫，對(duì)文檔進(jìn)行更改，在本地對(duì)其進(jìn)行測(cè)試，將其提交至git（我們的源代碼控制修訂系統(tǒng)），然后將其上傳至OpenStack的Gerrit實(shí)例。Gerrit然后向Jenkins發(fā)送通知，通知它有新的更改，Jenkins為軟件開發(fā)提供了持續(xù)的集成服務(wù)。一旦來自Gerrit的通知通過，Jenkins將運(yùn)行為存儲(chǔ)庫配置的各種測(cè)試套件。實(shí)際上，OpenStack并行運(yùn)行八個(gè)Jenkins實(shí)例，并使用稱為Zuul的自產(chǎn)工具進(jìn)行協(xié)調(diào)。您可以在Zuul網(wǎng)站上查看任何給定版本的狀態(tài)。

一旦將更改上傳到Gerrit，審閱者就可以看到更改并開始對(duì)此進(jìn)行評(píng)論。Gerrit的Web用戶界面允許逐行查看更改。因此，審閱者可以直接對(duì)源文件中發(fā)現(xiàn)的任何問題發(fā)表評(píng)論。我們還實(shí)施了構(gòu)建文檔的測(cè)試，以便審閱者在適用時(shí)可以查看HTML或PDF格式的文檔。

審核者對(duì)更改發(fā)表評(píng)論后，她也可以對(duì)更改進(jìn)行投票。在這里投票不是一個(gè)民主的過程，而是對(duì)補(bǔ)丁程序應(yīng)該加入的評(píng)估。審閱者可以投贊成票（是的，應(yīng)該投贊成票）或投反對(duì)票（需要更多的工作），或者只發(fā)表評(píng)論和棄權(quán)。

修改過的openstack文檔工作流程

每個(gè)人都可以通過以下投票在OpenStack的Gerrit中進(jìn)行評(píng)論：

• 0：無分?jǐn)?shù)

• +1：對(duì)我來說不錯(cuò)，但其他人必須批準(zhǔn)

• -1：此補(bǔ)丁程序需要進(jìn)一步的工作才能合并

我們還需要對(duì)補(bǔ)丁進(jìn)行評(píng)論，說明其錯(cuò)誤原因，需要澄清的問題或說明其正確性的原因。這些評(píng)論可幫助原始作者和其他審閱者更新和評(píng)估更改。

由高級(jí)審核員組成的特殊小組，即所謂的“核心審核員”，也可以進(jìn)行+2（或-2）投票并批準(zhǔn)一項(xiàng)更改，以便將其發(fā)布。這些評(píng)論通過以下任一方式指示：

• +2：對(duì)我看來不錯(cuò)（核心評(píng)論者）

• -2：不合并

一旦兩個(gè)核心審閱者給了+2，一個(gè)核心審閱者（通常是第二個(gè)對(duì)變更給予+2的人）批準(zhǔn)了變更，然后合并并發(fā)布。帶有負(fù)面評(píng)論的更改不會(huì)獲得批準(zhǔn)，因此只有在達(dá)成共識(shí)并獲得適當(dāng)批準(zhǔn)之前，文檔才能發(fā)布。

詹金斯（Jenkins）進(jìn)行的自動(dòng)測(cè)試也導(dǎo)致了審核階段的投票。變更獲得批準(zhǔn)后，Jenkins會(huì)再次運(yùn)行測(cè)試（將變更與當(dāng)時(shí)最新的git存儲(chǔ)庫合并），以確保不會(huì)出現(xiàn)任何退步。只有在Jenkins積極地檢查變更后，變更才能合并。

所有這些自動(dòng)更改都在HP和Rackspace公共云中運(yùn)行。目前，OpenStack項(xiàng)目為此使用多達(dá)950個(gè)虛擬機(jī)。對(duì)于每項(xiàng)測(cè)試作業(yè)，都將啟動(dòng)一臺(tái)計(jì)算機(jī)，在其中檢出測(cè)試變更的存儲(chǔ)庫中，安裝測(cè)試套件的所有依賴項(xiàng)，然后執(zhí)行測(cè)試套件。是的，我們正在將云用于有關(guān)云的文檔。

我們當(dāng)前運(yùn)行的測(cè)試在下面的部分中列出。

將CI / CD用于文檔有什么好處？

OpenStack每天都有多個(gè)項(xiàng)目合并多個(gè)更改，因此文檔系統(tǒng)還需要能夠跟上這么多更改。持續(xù)的集成和部署可以實(shí)現(xiàn)這一點(diǎn)，因此這不僅對(duì)我們帶來好處，而且對(duì)我們的環(huán)境是一項(xiàng)要求。作家具有與開發(fā)人員相同的工作流程，并獲得與開發(fā)人員相同的認(rèn)可和獎(jiǎng)勵(lì)。

我們還發(fā)現(xiàn)，盡管貢獻(xiàn)者仍然需要能夠在本地構(gòu)建文檔，但是它減輕了在本地編寫者環(huán)境中構(gòu)建文檔的負(fù)擔(dān)。通過準(zhǔn)備好草稿供審閱，臨時(shí)供稿人和審閱者可以避免下載補(bǔ)丁，復(fù)制構(gòu)建環(huán)境以及構(gòu)建文檔的開銷。由于系統(tǒng)的自動(dòng)化，我們可以查看源和輸出。

構(gòu)建速度加快了，因?yàn)樵诨谠频腃I / CD繼續(xù)運(yùn)行的同時(shí)，編寫者可以一次處理多個(gè)補(bǔ)丁。在OpenStack中，基礎(chǔ)架構(gòu)團(tuán)隊(duì)還使用許多相同的技術(shù)來管理服務(wù)器。

由于使用了測(cè)試腳本，編寫器始終從工作狀態(tài)開始，而主分支始終在構(gòu)建。如果文檔不在本地或在其他環(huán)境中構(gòu)建，那么作者可以確定這是他自己的錯(cuò)，而不是已經(jīng)損壞的樹。

草稿文檔的構(gòu)建和發(fā)布使審閱者可以快速檢查更改在發(fā)布時(shí)如何呈現(xiàn)。他們不需要在本地下載和構(gòu)建，因此可以更快地進(jìn)行審核。

我們還使用了與OpenStack開發(fā)人員和基礎(chǔ)架構(gòu)團(tuán)隊(duì)相同的工作流，這使開發(fā)人員可以輕松地為文檔做出貢獻(xiàn)。隨著我們最近轉(zhuǎn)向RST作為格式，它變得更加容易，因?yàn)镽ST是OpenStack中使用的通用標(biāo)記語言。

自動(dòng)化風(fēng)險(xiǎn)和陷阱

考慮到寫作既是一門藝術(shù)又是一門手工藝，因此我們確實(shí)嘗試在應(yīng)該自動(dòng)進(jìn)行的工作和仍然需要高級(jí)手工藝的工作之間取得平衡。早期的擔(dān)憂是發(fā)布時(shí)間太早，或者發(fā)布的文檔不完整。我們發(fā)現(xiàn)，只要審閱者有諸如“比現(xiàn)在更好的指南”或“我已經(jīng)對(duì)其進(jìn)行了測(cè)試并且知道它可以正常工作”或“此文檔修復(fù)與我調(diào)查過的報(bào)告錯(cuò)誤相匹配”之類的準(zhǔn)則，那么每天發(fā)布50-100次更新的風(fēng)險(xiǎn)降低了。

我們必須在審稿人之間建立信任，并且在我們?yōu)槠诹鶄€(gè)月的峰會(huì)上，我們?nèi)匀粫?huì)就審稿進(jìn)行現(xiàn)場(chǎng)討論。我們編寫了審閱指南 ，并試圖培訓(xùn)審閱者在審閱補(bǔ)丁時(shí)如何使用最佳判斷力。我們還編寫了一套審核指南。持續(xù)集成不僅是我們發(fā)布速度的一部分，而且讓值得信賴的審稿人使用良好的判斷力，同時(shí)讓機(jī)器人測(cè)試審閱使他們有信心，他們不必?fù)?dān)心文檔不會(huì)生成或我們會(huì)中斷整個(gè)文檔站點(diǎn)一夜之間。

我們有一些與發(fā)行版無關(guān)的手冊(cè)以及記錄當(dāng)前發(fā)行版的手冊(cè)。對(duì)于記錄特定發(fā)行版的手冊(cè)（如安裝指南），我們?yōu)槊總€(gè)新發(fā)行版進(jìn)行更新，并在分支機(jī)構(gòu)中工作。已發(fā)布的文檔進(jìn)行了重要更改，而下一個(gè)版本的文檔則進(jìn)行了大部分更改，并發(fā)布在隱藏的位置，以方便查看當(dāng)前草案。在軟件發(fā)行版發(fā)布后，我們會(huì)公開發(fā)布這些特定于發(fā)行版的指南，然后開始為下一個(gè)發(fā)行版進(jìn)行更新。

文件測(cè)試

Jenkins允許執(zhí)行腳本，并且文檔團(tuán)隊(duì)擁有自己的包含測(cè)試腳本的存儲(chǔ)庫，其中大多數(shù)是用Python編寫的。我們使用與文檔相同的工作流程來開發(fā)這些腳本。一旦進(jìn)行了重大更改，就完成了測(cè)試工具的發(fā)布，然后將該版本用于測(cè)試任何文檔更改。在文檔存儲(chǔ)庫中，我們使用test-requirments.txt文件的Python約定，該約定指示哪個(gè)發(fā)行版的openstack-doc-tools與給定的一組文檔源文件一起使用。

為了使審閱者可以專注于內(nèi)容，而不必費(fèi)力地選擇表格，自動(dòng)測(cè)試可以為我們處理大部分的選擇。但是，我們并不需要通過所有自動(dòng)測(cè)試才能發(fā)布文檔。有些測(cè)試被標(biāo)記為“投票”，這意味著除非通過所有這些測(cè)試，否則文檔不會(huì)合并。其他測(cè)試被標(biāo)記為“無投票權(quán)”，這意味著即使測(cè)試失敗，我們也允許補(bǔ)丁著陸。自動(dòng)測(cè)試是：

檢查單個(gè)文件的語法。這有助于快速定位語法錯(cuò)誤。可以針對(duì)DocBook XML，WADL XML，RST和JSON格式測(cè)試語法，但是我們僅測(cè)試DocBook XML和RST。在其他測(cè)試中，將檢查JSON的格式是否正確。

檢查文檔是否生成。這樣做的附帶好處是，將生成的指南上載到草稿服務(wù)器，以便審閱者可以輕松地審閱新生成的書籍，并查看HTML和PDF中的更改外觀。

檢查翻譯的手冊(cè)是否貫穿整個(gè)工具鏈。

檢查文件是否“不錯(cuò)”。這會(huì)根據(jù)文件類型（XML，RST或JSON）進(jìn)行檢查，檢查是否存在多余的空格，超長(zhǎng)行，某些不需要的unicode字符或正確的格式（JSON）。多余的空格和太長(zhǎng)的行使得并排查看源文件更加困難。我們的工具鏈無法輸出某些Unicode字符，并且JSON文件應(yīng)符合格式標(biāo)準(zhǔn)。

檢查到外部網(wǎng)站的鏈接是否有效。這將檢查已更改的DocBook XML文件中的所有URL是否都可以訪問。由于網(wǎng)站可能已關(guān)閉，此更改被標(biāo)記為“無投票權(quán)”。

檢查是否沒有刪除其他手冊(cè)使用的XML文件。這很重要，因?yàn)槲覀冎粯?gòu)建更改過的手冊(cè)，因此，如果刪除一個(gè)文件，我們必須檢查所有手冊(cè)仍然可以構(gòu)建。

我們還對(duì)測(cè)試腳本進(jìn)行了一些優(yōu)化。例如，由于DocBook XML文件的構(gòu)建成本很高，因此，小的依賴項(xiàng)構(gòu)建器會(huì)檢查哪些文件已更改以及哪些指南包括這些文件，然后僅構(gòu)建那些指南。其他測(cè)試（例如語法或URL檢查）也僅在更改后的文件上運(yùn)行。沒有理由一遍又一遍地檢查未更改的文件，雖然測(cè)試單個(gè)文件可能很快，但是測(cè)試近一千個(gè)XML文件卻很慢。

這些優(yōu)化目前尚未在RST文件上完成，因?yàn)镽ST文件更容易解析，并且指南的構(gòu)建也更快。

我們不會(huì)運(yùn)行任何語法或拼寫檢查器，因?yàn)橥镀睓z查必須始終準(zhǔn)確。關(guān)于自動(dòng)進(jìn)行拼寫檢查，我們進(jìn)行了很多討論，但這確實(shí)需要人眼來判斷。

CI基礎(chǔ)結(jié)構(gòu)的其他用途

我們用它來與我們的翻譯服務(wù)器對(duì)話。翻譯團(tuán)隊(duì)使用翻譯服務(wù)器（當(dāng)前為Transifex）來翻譯手冊(cè)。每當(dāng)合并更改時(shí)，CI基礎(chǔ)結(jié)構(gòu)都會(huì)自動(dòng)將當(dāng)前文本上載到翻譯服務(wù)器，以便翻譯人員可以直接翻譯并始終擁有最新的字符串。每天一次，在CI基礎(chǔ)架構(gòu)上運(yùn)行所謂的“定期”作業(yè)，以將所有翻譯后的字符串從翻譯服務(wù)器下載到文檔存儲(chǔ)庫，然后建議對(duì)任何新字符串進(jìn)行更改。這使我們有機(jī)會(huì)通過CI基礎(chǔ)結(jié)構(gòu)以及手動(dòng)審核來運(yùn)行翻譯導(dǎo)入。

此外，我們使用CI基礎(chǔ)結(jié)構(gòu)將一些共享文件從一個(gè)存儲(chǔ)庫同步到另一些存儲(chǔ)庫。這些文件是我們共享的術(shù)語表和共享的“支持附錄”及其翻譯。將更改合并到這些文件的主存儲(chǔ)庫后，將檢查其他存儲(chǔ)庫中的文件是否需要更新，如果是這種情況，則建議對(duì)該存儲(chǔ)庫進(jìn)行更改。同樣，這允許在導(dǎo)入時(shí)運(yùn)行測(cè)試套件并進(jìn)行最終的手動(dòng)檢查。

概要

希望本文為您提供有關(guān)我們?nèi)绾卧贠penStack文檔過程中使用持續(xù)集成和部署的想法。我們發(fā)現(xiàn)，該方法帶來的好處遠(yuǎn)大于任何風(fēng)險(xiǎn)。我們需要與其他團(tuán)隊(duì)進(jìn)行比賽，這意味著我們采用了持續(xù)不斷的心態(tài)，希望提早并經(jīng)常發(fā)貨。著眼于自動(dòng)化，看一下您的開源文檔，看看會(huì)出現(xiàn)什么。