GitLab Docs monthly release process · Gitlab 中文文檔

# GitLab Docs monthly release process > 原文：[https://docs.gitlab.com/ee/development/documentation/site_architecture/release_process.html](https://docs.gitlab.com/ee/development/documentation/site_architecture/release_process.html) * [How to build the images](#how-to-build-the-images) * [Monthly release process](#monthly-release-process) * [1\. Add the chart version](#1-add-the-chart-version) * [2\. Create an image for a single version](#2-create-an-image-for-a-single-version) * [3\. Create the release merge request](#3-create-the-release-merge-request) * [4\. Update the dropdown for all online versions](#4-update-the-dropdown-for-all-online-versions) * [5\. Merge the release merge request](#5-merge-the-release-merge-request) * [Update an old Docker image with new upstream docs content](#update-an-old-docker-image-with-new-upstream-docs-content) * [Porting new website changes to old versions](#porting-new-website-changes-to-old-versions) * [Troubleshooting](#troubleshooting) * [`test_internal_links_and_anchors` failing on dropdown merge requests](#test_internal_links_and_anchors-failing-on-dropdown-merge-requests) # GitLab Docs monthly release process[](#gitlab-docs-monthly-release-process "Permalink") [`dockerfiles`目錄](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/dockerfiles/)包含構建和部署版本控制網站所需的所有 Dockerfile. 它在很大程度上受到了 Docker 的[Dockerfile 的](https://github.com/docker/docker.github.io/blob/06ed03db13895bfe867761b6fc2ad40acf6026dd/Dockerfile)啟發. 使用以下 Dockerfile. | Dockerfile | Docker 鏡像 | Description | | --- | --- | --- | | [`Dockerfile.bootstrap`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/dockerfiles/Dockerfile.bootstrap) | `gitlab-docs:bootstrap` | 包含構建網站所需的所有依賴項. 如果寶石已更新且`Gemfile{,.lock}`更改，則必須重建映像. | | [`Dockerfile.builder.onbuild`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/dockerfiles/Dockerfile.builder.onbuild) | `gitlab-docs:builder-onbuild` | 用于建立 docs 網站的基本圖片. 它使用`ONBUILD`執行所有步驟，并取決于`gitlab-docs:bootstrap` . | | [`Dockerfile.nginx.onbuild`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/dockerfiles/Dockerfile.nginx.onbuild) | `gitlab-docs:nginx-onbuild` | 用于構建文檔檔案的基本映像. 它使用`ONBUILD`執行所有必需的步驟來復制檔案，并依賴于其父`Dockerfile.builder.onbuild` ，該父文件在構建單個文檔檔案時被調用（請參閱每個分支的`Dockerfile` . | | [`Dockerfile.archives`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/dockerfiles/Dockerfile.archives) | `gitlab-docs:archives` | 在一個檔案中包含網站的所有版本. 它從一個位置中的每個版本復制所有生成的 HTML 文件. | ## How to build the images[](#how-to-build-the-images "Permalink") 盡管構建映像是通過 GitLab CI / CD 自動構建的，但是您可以在本地構建和標記所有工具映像： 1. 確保已[安裝 Docker](https://s0docs0docker0com.icopy.site/install/) . 2. 確保您位于`gitlab-docs`存儲庫的`dockerfiles/`目錄中. 3. 構建圖像： ``` docker build -t registry.gitlab.com/gitlab-org/gitlab-docs:bootstrap -f Dockerfile.bootstrap ../ docker build -t registry.gitlab.com/gitlab-org/gitlab-docs:builder-onbuild -f Dockerfile.builder.onbuild ../ docker build -t registry.gitlab.com/gitlab-org/gitlab-docs:nginx-onbuild -f Dockerfile.nginx.onbuild ../ ``` 對于每個圖像， [`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/.gitlab-ci.yml)的`images`階段下都有一個手動作業，可以隨意調用. ## Monthly release process[](#monthly-release-process "Permalink") 當 22 日發布新版本的 GitLab 時，我們需要創建相應的單個 Docker 映像，并更新一些文件，以使下拉列表正常工作. ### 1\. Add the chart version[](#1-add-the-chart-version "Permalink") 由于圖表使用的版本號不同于所有其他 GitLab 產品，因此我們需要添加一個[版本映射](https://docs.gitlab.com/charts/installation/version_mappings.html) ： 1. 檢查是否為新的圖表版本[創建](https://gitlab.com/gitlab-org/charts/gitlab/-/branches)了[穩定的分支](https://gitlab.com/gitlab-org/charts/gitlab/-/branches) . 如果不確定或找不到，請在`#g_delivery`頻道中添加一行. 2. 確保您位于`gitlab-docs`存儲庫的根路徑中. 3. 打開`content/_data/chart_versions.yaml`并使用版本映射添加新的穩定分支版本. 請注意，僅需要`major.minor`版本. 4. 創建一個新的合并請求并將其合并. **提示：**創建將來的映射可能很方便，因為它們已廣為人知. 在這種情況下，當發布新版本的 GitLab 時，您不必重復此第一步. ### 2\. Create an image for a single version[](#2-create-an-image-for-a-single-version "Permalink") 必須在發布合并請求之前創建單個 docs 版本，但這需要在為所有產品創建穩定分支之后發生. 1. 確保您位于`gitlab-docs`存儲庫的根路徑中. 2. 運行 Rake 任務以創建單個版本： ``` ./bin/rake "release:single[12.0]" ``` 應該已經創建了新的`Dockerfile.12.0`并且`.gitlab-ci.yml`應該將分支變量更新為新的分支. 他們將被自動提交. 3. 推送新創建的分支，但**不要創建合并請求** . 推送后， `image:docker-singe`作業將創建一個新的 Docker 映像，該映像標記有您在第一步中創建的分支名稱. 最后，該圖像將被上載到[Container Registry 中](https://gitlab.com/gitlab-org/gitlab-docs/container_registry) ，并且將在位于`https://gitlab.com/gitlab-org/gitlab-docs/-/environments/folders/registry`的`registry`環境文件夾下列出.開發人員訪問權限）. （可選）您可以通過構建映像并運行它來進行本地測試： ``` docker build -t docs:12.0 -f Dockerfile.12.0 . docker run -it --rm -p 4000:4000 docs:12.0 ``` 訪問`http://localhost:4000/12.0/`以查看一切是否正常. ### 3\. Create the release merge request[](#3-create-the-release-merge-request "Permalink") **Note:** To be [automated](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/750). 現在是時候創建每月發布合并請求，添加新版本并輪換舊版本了： 1. 確保您位于`gitlab-docs`存儲庫的根路徑中. 2. 創建一個分支`release-XY` ： ``` git checkout master git checkout -b release-12-0 ``` 3. **輪換在線和離線版本：** 在任何給定時間，都有 4 個可瀏覽的在線版本：一個是從上游主分支（GitLab.com 的文檔）中提取的，另一個是三個最新的穩定版本. 編輯`content/_data/versions.yaml`并旋轉版本以反映新的更改： * `online` ：3 個最新的穩定版本. * `offline` ：所有以前的版本都以脫機存檔的形式提供. 4. **更新`:latest`和`:archives` Docker 映像：** 需要更新以下兩個 Dockerfile： 1. `dockerfiles/Dockerfile.archives`在列表頂部添加最新版本. 2. `Dockerfile.master`旋轉版本（最舊的被刪除，最新的被添加在列表的頂部）. 5. 最后，應該總共更改了四個文件. 提交并使用"發布"模板推送以創建合并請求： ``` git add content/ Dockerfile.master dockerfiles/Dockerfile.archives git commit -m "Release 12.0" git push origin release-12-0 ``` ### 4\. Update the dropdown for all online versions[](#4-update-the-dropdown-for-all-online-versions "Permalink") 版本下拉列表采用"硬編碼"方式. 在構建站點時，它將查看`content/_data/versions.yaml`的內容，并基于此內容填充下拉列表. 因此，較舊的分支將具有不同的內容，這意味著下拉列表將在后面列出一個或多個版本. 請記住，下拉菜單的新更改包含在未合并的`release-XY`分支中. The content of `content/_data/versions.yaml` needs to change for all online versions: 1. 運行 Rake 任務，該任務將創建更新下拉列表所需的所有各個合并請求，并將其設置為在管道成功后自動合并. `release-XY`分支需要在本地存在，并且您需要切換到該分支，否則 Rake 任務將失敗： ``` ./bin/rake release:dropdowns ``` 2. [訪問合并請求頁面](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests?label_name[]=release)以檢查其管道是否通過，并在所有管道合并后繼續進行以下也是最后一步. **提示：**萬一管道發生故障，請參閱[故障排除](#troubleshooting) . ### 5\. Merge the release merge request[](#5-merge-the-release-merge-request "Permalink") 下拉合并請求現在應該已經合并到各自的版本（穩定分支）中，這將觸發另一個管道. 在這一點上，您只需要照看管道，并確保它們不會失敗： 1. 檢查管道頁面： `https://gitlab.com/gitlab-org/gitlab-docs/pipelines` : `https://gitlab.com/gitlab-org/gitlab-docs/pipelines`并確保所有穩定的分支都具有綠色管道. 2. 聯機版本的所有管道成功后，請合并發布合并請求. 3. 最后，從`https://gitlab.com/gitlab-org/gitlab-docs/pipeline_schedules`運行`Build docker images weekly` Docker 映像管道，以構建`:latest`和`:archives` Docker 映像. 一旦計劃的管道成功，將在線部署所有新版本的 docs 網站. ## Update an old Docker image with new upstream docs content[](#update-an-old-docker-image-with-new-upstream-docs-content "Permalink") 如果對單個 Docker 映像中未包含的產品的任何穩定分支進行了任何更改，只需重新運行管道（ `https://gitlab.com/gitlab-org/gitlab-docs/pipelines/new` ）有問題的版本. ## Porting new website changes to old versions[](#porting-new-website-changes-to-old-versions "Permalink") **警告：將**更改移植到較舊的分支機構可能會產生意想不到的影響，因為我們不斷更改網站的后端. 僅在知道自己在做什么并確保在本地進行測試時使用. 網站將不斷變化和完善. 為了將這些更改合并到穩定分支中，我們需要不時選擇某些更改. 如果這不可能或有很多更改，請將 master 合并到其中： ``` git branch 12.0 git fetch origin master git merge origin/master ``` ## Troubleshooting[](#troubleshooting "Permalink") 發布新版本是一個漫長的過程，涉及許多活動部件. ### `test_internal_links_and_anchors` failing on dropdown merge requests[](#test_internal_links_and_anchors-failing-on-dropdown-merge-requests "Permalink") **注意：**我們現在將版本`.gitlab-ci.yml`在相應分支的`.gitlab-ci.yml`中，因此不建議使用以下步驟. 當[更新穩定版本的下拉列表時](#4-update-the-dropdown-for-all-online-versions) ，某些鏈接可能會失敗. 創建下拉式 MR 的過程有一個警告，那就是通過拉動所有產品的主分支而不是相應的穩定分支來運行測試. 在實際情況下，由于[`test_internal_links_and_anchors` test](https://gitlab.com/gitlab-org/gitlab-docs/-/jobs/328042431) [，導致與 12.4](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/604)合并請求[相匹配](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/604)的[Update 12.2 下拉列表](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/604)失敗. 發生這種情況是因為已經對產品進行了重命名（ `gitlab-monitor`到`gitlab-exporter` ），而舊名稱仍在 12.2 文檔中引用. 如果使用了 12.2 的各個穩定分支，則不會失敗，但是從[`compile_dev`作業中](https://gitlab.com/gitlab-org/gitlab-docs/-/jobs/328042427)可以看出， `master`分支已被拉出. 要解決此問題， `https://gitlab.com/gitlab-org/gitlab-docs/pipelines/new`為`update-12-2-for-release-12-4`分支重新運行管道（ `https://gitlab.com/gitlab-org/gitlab-docs/pipelines/new` ），以下環境變量： * `BRANCH_CE`設置為`12-2-stable` * `BRANCH_EE`設置為`12-2-stable-ee` * `BRANCH_OMNIBUS`設置為`12-2-stable` * `BRANCH_RUNNER`設置為`12-2-stable` * `BRANCH_CHARTS`設置為`2-2-stable` 這應該使 MR 通過.