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

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

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

CI / CD文檔

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

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

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

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

修改過的openstack文檔工作流程

每個人都可以通過以下投票在OpenStack的Gerrit中進行評論：

• 0：無分數(shù)

• +1：對我來說不錯，但其他人必須批準

• -1：此補丁程序需要進一步的工作才能合并

我們還需要對補丁進行評論，說明其錯誤原因，需要澄清的問題或說明其正確性的原因。這些評論可幫助原始作者和其他審閱者更新和評估更改。

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

• +2：對我看來不錯（核心評論者）

• -2：不合并

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

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

所有這些自動更改都在HP和Rackspace公共云中運行。目前，OpenStack項目為此使用多達950個虛擬機。對于每項測試作業(yè)，都將啟動一臺計算機，在其中檢出測試變更的存儲庫中，安裝測試套件的所有依賴項，然后執(zhí)行測試套件。是的，我們正在將云用于有關云的文檔。

我們當前運行的測試在下面的部分中列出。

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

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

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

構建速度加快了，因為在基于云的CI / CD繼續(xù)運行的同時，編寫者可以一次處理多個補丁。在OpenStack中，基礎架構團隊還使用許多相同的技術來管理服務器。

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

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

我們還使用了與OpenStack開發(fā)人員和基礎架構團隊相同的工作流，這使開發(fā)人員可以輕松地為文檔做出貢獻。隨著我們最近轉向RST作為格式，它變得更加容易，因為RST是OpenStack中使用的通用標記語言。

自動化風險和陷阱

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

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

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

文件測試

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

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

檢查單個文件的語法。這有助于快速定位語法錯誤?？梢葬槍ocBook XML，WADL XML，RST和JSON格式測試語法，但是我們僅測試DocBook XML和RST。在其他測試中，將檢查JSON的格式是否正確。

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

檢查翻譯的手冊是否貫穿整個工具鏈。

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

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

檢查是否沒有刪除其他手冊使用的XML文件。這很重要，因為我們只構建更改過的手冊，因此，如果刪除一個文件，我們必須檢查所有手冊仍然可以構建。

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

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

我們不會運行任何語法或拼寫檢查器，因為投票檢查必須始終準確。關于自動進行拼寫檢查，我們進行了很多討論，但這確實需要人眼來判斷。

CI基礎結構的其他用途

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

此外，我們使用CI基礎結構將一些共享文件從一個存儲庫同步到另一些存儲庫。這些文件是我們共享的術語表和共享的“支持附錄”及其翻譯。將更改合并到這些文件的主存儲庫后，將檢查其他存儲庫中的文件是否需要更新，如果是這種情況，則建議對該存儲庫進行更改。同樣，這允許在導入時運行測試套件并進行最終的手動檢查。

概要

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