# 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 通过.