GitLab Docs monthly release process

原文：https://docs.gitlab.com/ee/development/documentation/site_architecture/release_process.html

• How to build the images

• Monthly release process

  • 1. Add the chart version
  • 2. Create an image for a single version
  • 3. Create the release merge request
  • 4. Update the dropdown for all online versions
  • 5. Merge the release merge request

• Update an old Docker image with new upstream docs content

• Porting new website changes to old versions
• Troubleshooting
  • test_internal_links_and_anchors failing on dropdown merge requests

GitLab Docs monthly release process

dockerfiles目录包含构建和部署版本控制网站所需的所有 Dockerfile. 它在很大程度上受到了 Docker 的Dockerfile 的启发.

使用以下 Dockerfile.

How to build the images

尽管构建映像是通过 GitLab CI / CD 自动构建的，但是您可以在本地构建和标记所有工具映像：

1. 确保已安装 Docker .
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的images阶段下都有一个手动作业，可以随意调用.

Monthly release process

当 22 日发布新版本的 GitLab 时，我们需要创建相应的单个 Docker 映像，并更新一些文件，以使下拉列表正常工作.

1. Add the chart version

由于图表使用的版本号不同于所有其他 GitLab 产品，因此我们需要添加一个版本映射 ：

1. 检查是否为新的图表版本创建了稳定的分支 . 如果不确定或找不到，请在#g_delivery频道中添加一行.
2. 确保您位于gitlab-docs存储库的根路径中.
3. 打开content/_data/chart_versions.yaml并使用版本映射添加新的稳定分支版本. 请注意，仅需要major.minor版本.
4. 创建一个新的合并请求并将其合并.

提示：创建将来的映射可能很方便，因为它们已广为人知. 在这种情况下，当发布新版本的 GitLab 时，您不必重复此第一步.

2. Create an image for a single version

必须在发布合并请求之前创建单个 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/-/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

Note: To be automated.

现在是时候创建每月发布合并请求，添加新版本并轮换旧版本了：

1. 确保您位于gitlab-docs存储库的根路径中.

2. 创建一个分支release-XY ：

   git checkout master
   git checkout -b release-12-0 

   1. 轮换在线和离线版本：

   在任何给定时间，都有 4 个可浏览的在线版本：一个是从上游主分支（GitLab.com 的文档）中提取的，另一个是三个最新的稳定版本.

   编辑content/_data/versions.yaml并旋转版本以反映新的更改：

   • online ：3 个最新的稳定版本.
   • offline ：所有以前的版本都以脱机存档的形式提供.

3. 更新:latest和:archives Docker 映像：

   需要更新以下两个 Dockerfile：

   1. dockerfiles/Dockerfile.archives在列表顶部添加最新版本.
   2. Dockerfile.master旋转版本（最旧的被删除，最新的被添加在列表的顶部）.

4. 最后，应该总共更改了四个文件. 提交并使用"发布"模板推送以创建合并请求：

   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

版本下拉列表采用"硬编码"方式. 在构建站点时，它将查看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 

   1. 访问合并请求页面以检查其管道是否通过，并在所有管道合并后继续进行以下也是最后一步.

提示：万一管道发生故障，请参阅故障排除 .

5. Merge the release merge request

下拉合并请求现在应该已经合并到各自的版本（稳定分支）中，这将触发另一个管道. 在这一点上，您只需要照看管道，并确保它们不会失败：

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

如果对单个 Docker 映像中未包含的产品的任何稳定分支进行了任何更改，只需重新运行管道（ https://gitlab.com/gitlab-org/gitlab-docs/pipelines/new ）有问题的版本.

Porting new website changes to old versions

警告：将更改移植到较旧的分支机构可能会产生意想不到的影响，因为我们不断更改网站的后端. 仅在知道自己在做什么并确保在本地进行测试时使用.

网站将不断变化和完善. 为了将这些更改合并到稳定分支中，我们需要不时选择某些更改.

如果这不可能或有很多更改，请将 master 合并到其中：

git branch 12.0
git fetch origin master
git merge origin/master 

Troubleshooting

发布新版本是一个漫长的过程，涉及许多活动部件.

test_internal_links_and_anchors failing on dropdown merge requests

注意：我们现在将版本.gitlab-ci.yml在相应分支的.gitlab-ci.yml中，因此不建议使用以下步骤.

当更新稳定版本的下拉列表时 ，某些链接可能会失败. 创建下拉式 MR 的过程有一个警告，那就是通过拉动所有产品的主分支而不是相应的稳定分支来运行测试.

在实际情况下，由于test_internal_links_and_anchors test ，导致与 12.4合并请求相匹配的Update 12.2 下拉列表失败.

发生这种情况是因为已经对产品进行了重命名（ gitlab-monitor到gitlab-exporter ），而旧名称仍在 12.2 文档中引用. 如果使用了 12.2 的各个稳定分支，则不会失败，但是从compile_dev作业中可以看出， 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 通过.