istio.io
1.0.0
| 地點 | 地位 |
|---|---|
| istio.io | |
| preliminary.istio.io | |
| Archive.istio.io |
該存儲庫包含istio.io和preliminary.istio.io的源代碼。
請參閱主要的ISTIO讀數文件，以了解整體ISTIO項目以及如何與我們聯繫。要了解如何為任何ISTIO組件做出貢獻，請參閱ISTIO貢獻指南。
要了解如何編輯和構建此存儲庫的內容，請參考創建和編輯頁面。
ISTIO維持其公共場所的兩個變體。
istio.io是主要站點，顯示了產品當前發布的文檔。 istio.io/archive包含了產品先前版本的文檔快照。這對於仍使用這些較舊版本的客戶很有用。
preliminary.istio.io包含用於下一個產品版本的主動更新文檔。
用戶可以使用每頁右上角的Gear菜單在網站的不同變化之間進行微不足道的導航。這兩個站點均在Netlify上託管。
文檔更改主要致力於istio.io的主分支。對該分支的更改會自動反映在proliminary.istio.io上。
istio.io的內容取自最新的Release-XXX分支。使用的特定分支由istio.io netlify項目的配置確定。
簽入主分支的更新將自動更新preliminary.istio.io，並且只能在Istio.io上反映下一次發布版本時，將來可能是幾個星期。如果您想在istio.io上立即反射一些更改，則需要檢查對主分支和當前版本分支的更改（名為Release release-1.7 release-<MAJOR>.<MINOR> 。
我們的基礎架構可以自動照顧此過程。如果您向主分支提交PR，並使用cherrypick/release-<MAJOR>.<MINOR>標籤註釋PR，則一旦將PR合併到主人中，它將合併到指定的發行分支中。
這是創建新文檔版本所需的步驟。假設當前版本的ISTIO為1.6，您希望介紹正在開發的1.7。
運行make prepare-1.7.0 ，僅此而已。這將從新的ISTIO源分支中獲取最新的參考文檔，然後將其列入content/en/docs/reference夾中。
對於正式發行之前的干式運行，Run make release-1.7.0-dry-run ，它將僅創建新的分支機構release-1.7-dry-run ，而不會觸摸任何其他分支。
發行當天，Run make release-1.7.0 。這使目標將更改master和release-1.6中的某些變量，並為新版本創建新的分支版本release-1.7 。
轉到Netlify上的istio.io項目，並執行以下操作：
將構建的分支從上一個發行版的分支更改為新版本分支，在這種情況下， release-1.7 （或適當的release-1.7-dry-run ）。
選擇觸發即時重建和重新部署的選項。
部署完成後，瀏覽istio.io並確保一切看起來都不錯。
轉到Google自定義搜索引擎，並執行以下操作：
從“高級”選項卡下載istio.io cse上下文文件。
在包含上一個版本的版本編號的文件頂部添加一個新的FacetItem。在這種情況下，這將是V1.6 。
將更新的CSE上下文文件上傳到網站。
在“設置”部分中，添加一個涵蓋上一個版本的存檔目錄的新站點。在這種情況下，網站URL將是istio.io/v1.6/* 。將此網站的標籤設置為上面創建的刻面項目的名稱（在這種情況下為V1.6 ）。
補丁發布前幾天，發布經理應通知Doc WG，並啟動了該版本的長期運行資格測試。此時，將DOC自動化測試移動以使用新版本來驗證自動化DOC測試通過。
要轉到新版本（請確保您在補丁的版本分支中）：
運行go get istio.io/istio@AXY && go mod tidy 。
使用go.*更改。
創建新的補丁發布涉及修改一些文件：
編輯data/args.yml ，然後將full_version字段更改為"AXY" 。這僅是current版本的補丁。
通過編輯Markdown File content/en/news/releases/AXx/announcing-AXY/index.md來完成發行版的發行說明。這是您描述發行版的更改的地方。請查看其他現有文件，例如內容和佈局。
運行make update_ref_docs獲取最新的參考文檔。通常，這僅是current版本的補丁。如果在較早的版本中需要，請參見更新檔案。
如果由於舊版本分支的更改（在這種情況下為release-1.7:archive/v1.6 release-1.6 ，您可以在Master Branch中運行make build-old-archive-1.6.0 ，在master Branch中，它將重新構建版本的release-1.6 ，並將其替換為master Branch的先前存檔。如果此更新需要反映在istio.io中，則PR可以挑選到分支機構以進行current版本。
以release-1.6開頭的發行流包含測試內容的測試。每個發布測試都針對特定的ISTIO版本/提交。當發布團隊有一個構建， 1.xy ，準備長期運行的測試時，他們應該來到文檔團隊進行該版本運行的測試，以開始與構建有關。
public和private建築有兩種類型。正常的開髮型和釋放構建是由我們的公共存儲庫構建的，並在公共可訪問的存儲庫中具有圖像，並被視為public 。 Private版本是我們在發布前無法透露太多的私人版本。通常，這是一個提前通知，即CVE將在兩週內發行。由於我們在實際發布之前無法透露任何內容，因此源和構建的圖像是私人存儲庫。由於來源和圖像是私人的，我們實際上不能搬到它們之前，直到它們公開發布，因此在istio.io中沒有對版本進行早期測試。 private構建的區別在於，我們測試的圖像從未在public gcr.io存儲庫中創建，因此在這種情況下，我們使用docker.io images。有人可能會問為什麼我們不總是使用docker.io的釋放圖像。由於我們想在發佈公共版本之前測試public構建，因此圖像尚不存在Docker.io上。
對於公共建築：
go get istio.io/istio@commit && go mod tidy 。對於私人構建（這是在發布構建後完成的）：
go get istio.io/[email protected] && go mod tidy 。對於這兩種構建，我們都想驗證Hub/Tag在makefile.core.mk中是否正確（它們會根據使用私人或公共構建而更改）。尋找類似的部分：
# If one needs to test before a docker.io build is available (using a public test build),
# the export HUB and TAG can be commented out, and the initial HUB un-commented
HUB ?= gcr.io/istio-testing
# export HUB ?= docker.io/istio
# export TAG ?= 1.7.3
對於公共構建， export HUB/TAG S將不受調，並具有正確的值。對於私人構建或master分支，將不受調。
最後，創建並提交具有更改的PR，並且可以在PR中看到測試結果。通常，在發布發布之前，PR實際上不會合併（有時有多個版本以供發布）。
ISTIO網站上的許多文檔都使用命令演示了功能，這些命令可能會隨著ISTIO的發行演變而演變而來的命令。為了確保記錄的說明保持最新的最新連續手動測試，我們創建了一個框架來自動化這些文檔的測試。
可以測試的ISTIO.IO上的每個頁面都包括頁面標題下的PAGE TEST指示。例如：
綠色檢查標記表明該頁面可進行自動測試。該頁面是最新的，並按照記錄的方式工作。
另一方面，灰色X意味著該頁面還沒有可用的自動測試。如果您想幫助創建一個，我們將不勝感激！我們的目標是最終為ISTIO網站上發布的每個可測試文檔進行自動測試。
有關更多信息，請參見測試讀數。
該網站被翻譯成多種語言。真理的來源是英語內容，而其他語言是派生的，因此傾向於稍微落後。每個站點語言都有自己的完全獨立的內容目錄和翻譯表文件。使用其國際2字母語言代碼來識別語言。主站點內容位於content/<language code> （例如content/en ）中，翻譯表是i18n<language code>.toml （例如i18n/en.toml ）中的toml-format文件。
開始翻譯非常簡單：
為您的語言創建content/en目錄的完整副本。例如，如果您正在進行法語翻譯，則將content/en複製到content/fr 。
更新新內容目錄中的所有鏈接，以指向您的內容目錄，而不是指向英語內容。例如，如果您正在進行法語翻譯，則將更改[a doc](/docs/a/b/c)等鏈接到[a doc](/fr/docs/a/b/c) 。
刪除所有內容頁面的前符號中的所有aliases指令。將頁面移至新位置時，使用了別名，因此對於全新的內容而言，它們並不理想。
為您的語言創建i18n/en.toml文件的副本。例如，如果您正在進行法語翻譯，則將i18n/en.toml複製到i18n/fr.toml 。該文件包含網站基礎架構顯示的文本，菜單和其他標準材料等內容。
編輯文件hugo.toml以列出您的新語言。搜索[languages]條目，只需添加一個新條目即可。這告訴Hugo網站生成器處理您的內容。
編輯文件scripts/lint_site.sh並蒐索check_content 。將另一個呼叫添加到您的新內容目錄中的check_content 。這樣可以確保覆蓋規則適用於您的新內容。
編輯文件src/ts/lang.ts並添加您的新語言。這將使您的語言添加到preliminary.istio.io上可用的語言切換按鈕中，並將其添加到該語言選擇菜單中。
獲取一個iStio github管理員，為您的語言創建一個新的維護者團隊。對於法國人來說，這將是WG - Docs Maintainers/French 。
編輯文件CODEOWNERS並為您的語言添加條目，以使您創建的新團隊對翻譯內容和翻譯表文件的所有權。
然後，您可以提交所有這些更改，並且可以以純粹的增量方式開始翻譯內容和翻譯文件。構建網站時，您將在<url>/<language code>上找到您的內容。例如，一旦您檢查了所有內容，如果您正在進行法語翻譯，您應該能夠在https://preliminary.istio.io/fr上找到您的內容。
一旦翻譯完成並準備好將其發布給世界，您還需要進行其他一些更改：
編輯文件layouts/index.redir 。搜索translated sites並為您的語言添加一行。這將導致用戶首次進入網站，自動將其重定向到適合他們的翻譯內容。對於法語，這將是：
/ /fr 302 Language=fr
編輯文件layouts/partials/headers.html 。搜索switch-lang ，您會找到語言選擇菜單的定義。為您的新語言添加一行。
就是這樣。
我們進行了許多檢查，以確保維護許多不變性，以幫助該網站的整體質量。例如，我們不允許檢查折斷的鏈接，並進行拼寫檢查。有些事情很難系統地檢查自動化，而要求人類在一段時間內進行審查，以確保一切順利。
在本網站的每個主要版本之前，最好瀏覽此列表是一個好主意：
確保對GitHub上的ISTIO存儲庫的引用不要硬碼分支名稱。搜索所有在所有標記文件中搜索/release-1或/master的用途，然後用{{<source_branch_name>}}}替換為{{<source_branch_name>}}}，該文件會產生適合版本的分支名稱。
查看.spelling文件中的單詞不應該在那裡。特別是類型名稱傾向於在此處爬行。類型名稱不應在字典中，而應以backticks為單位顯示。從字典中刪除條目，並修復出現的任何拼寫檢查錯誤。
確保適當的資本化。文檔標題需要充分資本化（例如“這是一個有效的標題”），而部分標題應僅使用首字母大寫（例如“這是有效的標題”）。
確保從istio github存儲庫中引用文件的預製文本塊使用@@語法來生成內容的鏈接。請參閱此處的上下文。
