Help us learn about your current experience with the documentation. Take the survey.

文档测试

GitLab 文档与代码一起存储在项目中，并被当作代码一样对待。 为了保持文档的标准和质量，我们使用与代码类似的流程。

包含 Markdown (.md) 文件更改的合并请求会运行以下 CI/CD 作业：

一些文件是由脚本生成的。当源代码文件或文档文件在没有遵循正确流程的情况下更新时，CI/CD 作业会失败：

  • graphql-verify：当 doc/api/graphql/reference/_index.md 未按照 更新流程 更新时失败。
  • docs-lint deprecations-and-removals：当 doc/update/deprecations.md 未按照 更新流程 更新时失败。

有关自动化文件的完整列表，请参阅 自动化页面。

lint-doc.sh 中的测试

/scripts/lint-doc.sh 中的测试 查找 Vale 和 markdownlint 无法测试的页面内容问题。 如果任何 lint-doc.sh 测试失败，docs-lint markdown 作业将失败：

Mermaid 图表检查

Mermaid 从代码构建图表和图表。

脚本 (scripts/lint/check_mermaid.mjs) 在 docs-lint mermaid 作业中运行， 适用于所有包含 Markdown 文件更改的合并请求。如果任何 Markdown 文件返回 Mermaid 语法错误， 脚本将返回错误。

要帮助调试您的 Mermaid 图表，请使用 Mermaid Live Editor。

为了检查断开的链接，包含 Markdown (.md) 文件更改的合并请求会在其流水线中运行以下作业：

这些作业检查链接，包括锚点链接，并报告任何问题。任何需要网络连接的链接都会被跳过。

翻译文档的测试

为确保我们所有翻译内容的质量，我们为多语言文档实现了测试。这些测试与英语版本使用的测试类似， 但在 /doc-locale/ 或 /docs-locale/ 目录中的国际化内容上运行。

项目 英文目录 翻译目录 检查作业
GitLab /doc /doc-locale docs-i18n-lint markdown
GitLab Runner /docs /docs-locale docs:lint i18n markdown
Linux 包 /doc /doc-locale docs-lint-i18n markdown
docs-lint-i18n content
Charts /doc /doc-locale check_docs_i18n_content
check_docs_i18n_markdown
Operator /doc /doc-locale docs-i18n-lint content
docs-i18n-lint markdown

孤立翻译文件的路径验证

如果 /doc-locale 中的翻译文件没有对应的英文源文件，docs-i18n-lint paths 作业将失败。该作业在以下情况下运行：

  • /doc-locale 中的文件被修改
  • 路径验证脚本被更改

当检测到孤立翻译文件时，本地化团队成员会处理必要的删除。英文回退内容在新翻译可用之前提供覆盖。

安装文档检查工具

为了帮助遵守 文档风格指南，并 改进添加到文档中的内容，请安装文档检查工具 并将它们与您的代码编辑器集成。至少安装 markdownlint 和 Vale 以匹配构建流水线中运行的检查。这两个工具都可以 与您的代码编辑器集成。

在本地运行文档测试

类似于 在本地预览您的更改，您也可以在 本地计算机上运行文档测试。这有以下优势：

  • 加速反馈循环。您可以在分支中了解任何更改问题， 而无需等待 CI/CD 流水线运行。
  • 降低成本。在本地运行测试比在 GitLab 使用的 云基础设施上运行测试更便宜。

重要的是要：

  • 保持工具更新，并 匹配我们在 CI/CD 流水线中使用的版本。
  • 以与 CI/CD 流水线中相同的方式运行检查器、文档链接测试和 UI 链接测试。使用我们在 CI/CD 流水线中使用的配置很重要，这可能不同于工具的默认配置。

在本地运行 Vale、markdownlint 或链接检查

安装和配置说明适用于：

在本地运行 lint-doc.sh

使用 Rake 任务在本地运行 lint-doc.sh 测试。

先决条件：

  • 您已：

  1. 进入您的 gitlab 目录。

  2. 运行：

    rake lint:markdown

要指定您想要运行检查检查的单个文件或目录，请运行：

MD_DOC_PATH=path/to/my_doc.md rake lint:markdown

输出应类似于：

=> 正在以 <user> 身份对 /path/to/gitlab 中的文档进行检查...
=> 检查 cURL 短选项...
=> 检查 CHANGELOG.md 重复条目...
=> 检查 /path/to/gitlab/doc 的可执行权限...
=> 检查新的 README.md 文件...
=> 检查 Markdown 风格...
=> 检查文体...
✔ 1 个文件中 0 个错误、0 个警告和 0 个建议。
✔ 检查通过

更新检查器配置

Vale 和 markdownlint 配置在每个项目中都处于源代码控制下， 因此更新必须单独提交到每个项目。

gitlab 项目中的配置应被视为事实来源， 所有更新应首先在那里进行。

定期，在 gitlab 项目中对 Vale 和 markdownlint 配置所做的更改 应同步到其他项目。在每个 支持的项目 中：

  1. 创建一个新分支。在分支名前添加 docs- 或在末尾添加 -docs。一些项目使用此 约定来限制运行的作业。

  2. 从 gitlab 项目复制配置文件。例如，在项目根目录中运行：

    # 复制 markdownlint 配置文件
cp ../gitlab/.markdownlint-cli2.yaml .
# 删除现有的 Vale 配置，以防某些规则已从 GitLab 项目中删除
rm -r docs/.vale/gitlab
# 复制 gitlab_base Vale 配置文件，用于文档存储在 'docs' 目录的项目
cp -r ../gitlab/doc/.vale/gitlab_base docs/.vale

  3. 如果更新 gitlab-runner、gitlab-omnibus、charts/gitlab 或 gitlab-operator，还要从 gitlab 项目复制 gitlab-docs Vale 配置。例如，在项目根目录中运行：

    # 复制 gitlab-docs Vale 配置文件，用于文档存储在 'docs' 目录的项目
cp -r ../gitlab/doc/.vale/gitlab_docs docs/.vale

  4. 审阅为 .markdownlint-cli2.yaml 创建的差异。例如，运行：

    git diff .markdownlint-cli2.yaml

  5. 删除任何不需要的更改。例如，customRules 仅在 gitlab 项目中使用。

  6. 审阅为 Vale 配置创建的差异。例如，运行：

    git diff docs

  7. 删除对 RelativeLinks.yml 的不需要的更改。此规则特定于每个项目。

  8. 删除任何 .tmpl 文件。这些文件仅在 gitlab 项目中使用。

  9. 运行 markdownlint-cli2 检查是否有违反新规则的情况。例如：

    markdownlint-cli2 docs/**/*.md

  10. 运行 Vale 检查是否有违反新规则的情况。例如：

    vale --minAlertLevel error docs

  11. 将更改提交到新分支。一些项目要求 使用约定式提交，因此在提交前请检查项目的贡献信息。

  12. 提交合并请求以供审查。

更新检查镜像

检查测试使用来自 docs-gitlab-com 容器注册表 的镜像在 CI/CD 流水线中运行。

如果发布了新版本的依赖项（如 Vale 的新版本），我们应该 更新镜像以使用新版本。然后，我们可以更新我们每个文档项目中的 配置文件以指向新镜像。

要更新检查镜像：

  1. 在 docs-gitlab-com 中，打开合并请求以更新 .gitlab-ci.yml 以使用新工具 版本。示例 MR
  2. 合并后，启动 Build docker images pipeline (Manual) 计划流水线。
  3. 转到您启动的流水线，等待相关的 test:image 作业完成， 例如 test:image:docs-lint-markdown。如果该作业：
    • 通过，启动相关的 image: 作业，例如 image:docs-lint-markdown。
    • 失败，审阅测试作业日志并开始排查问题。镜像配置 可能需要一些手动调整才能与更新的依赖项一起工作。
  4. image: 作业通过后，检查作业日志中新镜像的名称。 示例作业输出
  5. 验证新镜像是否已添加到容器注册表。
  6. 打开合并请求以更新这些配置文件以指向新镜像。 对于使用 markdownlint、vale 或 lychee 的作业：
  7. 在每个合并请求中：
    1. 包含一个小文档更新以触发使用该镜像的作业。
    2. 检查相关作业输出以确认使用了更新的镜像进行测试。
  8. 将合并请求分配给任何技术作者进行审查和合并。

配置 pre-push 钩子

Git pre-push 钩子 允许 Git 用户：

  • 在推送分支之前运行测试或其他流程。
  • 如果这些测试失败，避免推送分支。

Lefthook 是一个 Git 钩子管理器。它使配置、 安装和删除 Git 钩子更简单。其配置在 gitlab 项目的 lefthook.yml 文件中可用。

要为文档检查设置 Lefthook，请参阅 使用 Lefthook 进行提交前和推送前静态分析。

要在提交或推送时显示 Vale 错误，请参阅 在提交或推送时显示 Vale 警告。

在文档上禁用检查

一些（但不是全部）检查可以在文档文件上禁用：

CI/CD 流水线中使用的工具版本

您应该使用与我们在 CI/CD 流水线中使用的检查器版本相同的版本，以获得与我们使用的检查规则的最大兼容性。

要匹配 markdownlint-cli2 和 vale 在 GitLab 项目中使用的版本，请参阅：

这两个位置中设置的版本应该相同。

工具 版本 命令 其他信息
markdownlint-cli2 最新 yarn global add markdownlint-cli2 无。
markdownlint-cli2 特定 yarn global add markdownlint-cli2@0.8.1 @ 表示特定版本，此示例将工具更新到版本 0.8.1。
Vale（使用 asdf） 特定 asdf install 安装项目中 .tool-versions 文件中设置的 Vale 版本。
Vale（其他） 特定 不适用 二进制文件可以 直接下载。
Vale（使用 brew） 最新 brew update && brew upgrade vale 此命令仅适用于 macOS。

支持的项目

有关我们在 CI/CD 流水线中运行的每个测试的具体信息，请参阅相关项目中这些测试的配置：

我们还在这些项目中运行一些文档测试：