ドキュメンテーションテスト

GitLabドキュメントはコードと一緒にプロジェクトに保存され、コードと同じように扱われます。そのため、ドキュメントの標準と品質をメンテナーするために、コードと同じようなプロセスを用います。

テストがあります：

  • ドキュメンテーションの単語と構造をリントします。
  • ドキュメント群の内部リンクの妥当性をチェックします。
  • app/views ファイルのファイルなど、UI 要素からのリンクの有効性をチェックするため。

CI/CD パイプラインで実行される各テストの詳細については、関連するプロジェクトのテストの設定を参照してください：

また、いくつかのドキュメントテストも

ローカルでテストを実行

ローカルで変更をプレビューするのと同様に、ローカルコンピュータ上でテストを実行することもできます。これには次のような利点があります：

  • フィードバックループの高速化。CI/CD パイプラインの実行を待つことなく、ブランチの変更に問題があればそれを知ることができます。
  • コストの削減。ローカルでテストを実行することは、GitLabが使用するクラウドインフラ上でテストを実行するよりも安価です。

ローカルでテストを実行するには、以下のことが重要です：

Lintチェック

Markdown (.md) ファイルへの変更を含むマージリクエストはdocs-lint markdown ジョブを実行します。このジョブはmarkdownlint と、Valeとmarkdownlintがテストできないページ内容の問題を探す/scripts/lint-doc.sh からのテストのセットを実行します。これらのテストのいずれかが失敗した場合、ジョブは失敗します：

  • Curl (curl) コマンドは、-h のような短いオプションではなく、長い形式のオプション (--header) を使用する必要があります。
  • ドキュメント ページには、そのページの所有者を示すフロント マターを含める必要があります。
  • 非標準のUnicodeスペース文字(NBSP, NNBSP, ZWSP)は、検索インデックスやgreppingに不正を引き起こす可能性があるため、文書で使用してはいけません。
  • CHANGELOG.md 重複したバージョンを含んではいけません。
  • doc/ ディレクトリには実行可能なファイルはありません。
  • README.md の代わりにindex.md を使用してください。
  • ディレクトリ名とファイル名には、ダッシュの代わりにアンダースコアを使用する必要があります。
  • ディレクトリとファイル名は小文字でなければなりません。

ローカルでlintチェックを実行

Lintチェックはlint-doc.sh スクリプトによって実行され、以下のようにRakeタスクの助けを借りて実行することができます：

  1. gitlab ディレクトリに移動します。

  2. 以下を実行する:

    rake lint:markdown

lintチェックを実行したいファイルまたはディレクトリを1つ指定するには、実行します：

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

出力は以下のようになります：

=> Linting documents at path /path/to/gitlab as <user>...
=> Checking for cURL short options...
=> Checking for CHANGELOG.md duplicate entries...
=> Checking /path/to/gitlab/doc for executable permissions...
=> Checking for new README.md files...
=> Linting markdown style...
=> Linting prose...
✔ 0 errors, 0 warnings and 0 suggestions in 1 file.
✔ Linting passed

この場合、以下のいずれかを行う必要があります：

  • 必要なリントツールがコンピュータにインストールされていること。
  • Dockerまたはcontainerdがインストールされており、これらのツールがプリインストールされたイメージを使用できること。

Markdown (.md) ファイルへの変更を含むマージリクエストはdocs-lint links ジョブを実行し、2種類のリンクチェックを実行します。どちらの場合でも、http またはhttps で始まるリンク先は外部リンクとみなされ、スキップされます：

  • bundle exec nanoc check internal_links:内部ページへのリンクをテストします。
  • bundle exec nanoc check internal_anchors:内部ページのトピックタイトルアンカーへのリンクをテストします。

これらのテストの失敗は、テスト結果の最後にある「イシューが見つかりました！」エリアに表示されます。たとえば、internal_anchors テストでの失敗は、次のような形式で表示されます：

[ ERROR ] internal_anchors - Broken anchor detected!
  - source file `/tmp/gitlab-docs/public/ee/user/application_security/api_fuzzing/index.html`
  - destination `/tmp/gitlab-docs/public/ee/development/code_review.html`
  - link `../../../development/code_review.html#review-response-slo`
  - anchor `#review-response-slo`
  • ソースファイル：エラーを含むファイルへのフルパス。gitlab リポジトリでファイルを見つけるには、/tmp/gitlab-docs/public/ee をdoc に、.html を.mdに置き換えてください。
  • 宛先：テストで見つからなかったファイルへのフル パス。gitlab リポジトリでファイルを検索するには、/tmp/gitlab-docs/public/ee をdoc に、.html を.mdに置き換えます。
  • リンク：スクリプトが探そうとした実際のリンク。
  • アンカー：存在する場合、スクリプトが見つけようとしたトピックタイトルのアンカー。

エラーを報告している各ページで、同じリンク切れが複数インスタンス表示されていないかチェックします。特定のリンク切れがページに複数回表示されても、テストでは一度しか報告されません。

ドキュメント・リンク・テストをローカルで実行するには

  1. gitlab-docs ディレクトリに移動します。

  2. 以下のコマンドを実行してください：

    # Check for broken internal links
bundle exec nanoc check internal_links
   
# Check for broken external links (might take a lot of time to complete).
# This test is set to be allowed to fail and is run only in the gitlab-docs project CI
bundle exec nanoc check internal_anchors

ui-docs-links lint ジョブはhaml-lint を使って、UI 要素 (app/views ファイルなど) からのすべてのドキュメントリンクが有効な Pages とアンカーにリンクされているかテストします。

ui-docs-links テストを内部で実行するには：

  1. ターミナル・ウィンドウでgitlab ディレクトリを開きます。

  2. 以下を実行する:

    bundle exec haml-lint -i DocumentationLinks

このテストを最初に実行したときにエラーが発生した場合は、GitLabの依存関係をインストールするbundle install を実行して、もう一度試してください。

リンクをテストするためにすべての依存関係をインストールしたくない場合は、できます：

  1. ターミナル・ウィンドウでgitlab ディレクトリを開きます。

  2. haml-lint をインストールします：

    gem install haml_lint

  3. 以下を実行する:

    haml-lint -i DocumentationLinks

このプロセスでhaml-lint を手動でインストールした場合、自動的にアップデートされないので、お使いのバージョンが GitLab で使われているバージョンと一致していることを確認する必要があります。

linter 設定の更新

Valeの設定と markdownlintの設定は各プロジェクトでソース管理されているため、更新は各プロジェクトに個別にコミットする必要があります。

私たちはgitlab プロジェクトの設定を真実のソースとみなし、すべての更新はまずそこで行われるべきです。

定期的に、gitlab プロジェクトで行われた Vale と markdownlint の設定変更は、他のプロジェクトと同期されるべきです。omnibus-gitlab 、gitlab-runner 、charts/gitlab：

  1. 新しいブランチを作成します。
  2. gitlab プロジェクトの gitlab設定ファイルをこのgitlab ブランチに gitlabコピーしgitlab 、プロジェクトの古い設定を上書き gitlabします。gitlab プロジェクト固有の変更が gitlab含まれていないことを確認してください。たとえば、RelativeLinks.yml は特定のプロジェクト用にハードコーディングされています。
  3. マージリクエストを作成してテクニカルライターに提出し、レビュアーとマージしてもらいます。

リントイメージの更新

gitlab-docs コンテナレジストリからのイメージを使用して、CI/CDパイプラインで実行されるテストをリントします。

依存関係の新しいバージョンがリリースされたら（Rubyの新しいバージョンのように）、新しいバージョンを使うようにイメージを更新する必要があります。そして、各ドキュメンテーションプロジェクトの設定ファイルを更新して、新しいイメージを指すようにします。

linting イメージを更新するには

  1. gitlab-docsで、新しいツール・バージョンを使用するために.gitlab-ci.yml を更新するマージ・リクエストを開きます。(MRの例)
  2. マージされたら、Build docs.gitlab.com every hour スケジュールされたパイプラインを開始します。
  3. 開始したパイプラインに移動し、関連するビルドイメージジョブを手動で実行します。例えば、image:docs-lint-markdown 。
  4. ジョブの出力で、新しいイメージの名前を取得します。(ジョブ出力の例)
  5. 新しいイメージがコンテナ・レジストリに追加されたことを確認します。
  6. これらの各設定ファイルを更新して新しいイメージを指すようにマージリクエストを開きます。各マージリクエストに、イメージを使用するジョブをトリガーするための小さな doc 更新を含めます。
  7. 各マージリクエストで、関連するジョブ出力をチェックし、更新された画像がテストに使用されたことを確認します。(ジョブ出力の例)
  8. マージリクエストを任意のテクニカルライターに割り当て、レビューとマージを行ってもらいます。

ローカルリンター

ドキュメントスタイルガイドラインを遵守し、ドキュメントに追加される内容を改善するために、ドキュメントリンターをインストールし、コードエディターにインテグレーションしてください。

GitLabでは、主に次のものを使っています：

markdownlint

markdownlintはMarkdown構文が特定のルールに従っているかチェックし、docs-lint テストで使用されます。

私たちのドキュメントスタイルガイドと Markdownガイドは、GitLabドキュメントのためにMarkdown構文を選択するときにどのような選択をしなければならないかについて詳しく説明しています。このツールは、これらのガイドラインからの逸脱を検出するのに役立ちます。

markdownlintの設定は以下のプロジェクトにあります：

この設定はビルドパイプラインでも使用されます。

markdownlintを使うことができます：

マークダウン・ルールMD044/proper-names (大文字小文字の区別)

混乱を引き起こす可能性のあるルールはMD044/proper-names です。その失敗や修正方法はすぐにはわからないかもしれません。このルールは、各プロジェクトの.markdownlint.yml ファイルに記載されている既知の単語のリストをチェックし、大文字とバックスティックの適切な使用を確認します。バックティック内の単語は markdownlint によって無視されます。

一般的に、製品名は製品やプロトコルなどの正式名称の大文字小文字に正確に従うべきです。

間違った大文字が使われると失敗する例もあります：

  • MinIO (大文字が必要IO)
  • NGINX (すべて大文字が必要)
  • runit (小文字のr が必要)

さらに、コマンド、パラメータ、値、ファイル名などは、バックティックで囲む必要があります。例えば

  • “Change theneeds keyword in your.gitlab-ci.yml…”
    • needs はパラメータであり、.gitlab-ci.yml ファイルなので、両方ともバックティックが必要です .gitlab-ci.yml。.gitlab-ci.yml さらに .gitlab-ci.yml、大文字のGやLがないため、バックティックがないとmarkdownlintは失敗します。
  • “git clone を実行して Git リポジトリをクローンする…”
    • git clone はコマンドなので小文字でなければなりませんが、Git は製品なので大文字の G でなければなりません。

ベール

Valeは英語の文法・スタイル・語法リンターです。Valeの設定はプロジェクトのルートディレクトリにある.vale.ini ファイルに保存されます。

Valeは、いくつかのタイプのチェックを拡張するカスタムテストの作成をサポートしており、プロジェクトのドキュメントディレクトリにある.linting/vale/styles/gitlab ディレクトリに保存されます。

Vale の設定は、以下のプロジェクトで見ることができます：

この設定は、エラーレベルルールが適用されるビルドパイプラインでも使用されます。

Valeを使うことができます：

Valeの結果タイプ

Valeは3種類の結果を返します：

  • エラー- ブランディング・ガイドライン、商標ガイドライン、ドキュメント・サイトのコンテンツが正しくレンダリングされない原因となっているもの。
  • 警告- 一般的なスタイル・ガイドのルール、原則、ベスト・プラクティス。
  • 提案- 文書のリファクタリングや例外リストの更新が必要なテクニカルライティングスタイルの好み。

結果の型には以下の属性があります：

結果タイプCI/CDジョブの出力に表示されます。MR diffでの表示CI/CDジョブが失敗する原因ヴェイルルールリンク
error {チェックサークル｝はい {チェックサークル｝はい {チェックサークル｝はいエラーレベルベイルのルール
warning {点線円｝いいえ {チェックサークル｝はい {点線円｝いいえ警告レベルのValeルール
suggestion {点線円｝いいえ {点線円｝いいえ {点線円｝いいえ提案レベルのヴェイル・ルール

ベイルのスペルテスト

Valeが有効な単語にスペルミスのフラグを立てた場合、以下のガイドラインに従って修正することができます：

フラグが立った単語ガイドライン
専門用語それを避けるために文章を書き換えてください。
商品・サービス名 valeのスペル例外リストにその単語を追加します。
人名名前が不要な場合は削除するか、vale例外コードをインラインで追加してください。
コマンド、変数、コード、またはそれに類するもの。バックティックかコードブロックに入れてください。例：The git clone command can be used with the CI_COMMIT_BRANCH variable. ->The `git clone` command can be used with the `CI_COMMIT_BRANCH` variable.
GitLabのUIテキストUIと正しく一致しているか確認してください：UIと一致しない場合は更新してください。UI と一致するが UI が正しくないと思われる場合は、UI を修正する必要があるかどうかを確認するためにイシューを作成します。UIと一致し、正しいようであれば、スペルの例外リストに追加します。
サードパーティ製品のUIテキストそれを避けるように文章を書き直すか、ベール例外コードをインラインで追加してください。

ヴェイル大文字（頭文字）テスト

Uppercase.yml テストは、すべて大文字で表記された単語の誤った使い方をチェックします。例えば、This is NOT important のような使い方は避けてください。

単語をすべて大文字にしなければならない場合は、以下のガイドラインに従ってください：

フラグが立った単語ガイドライン
略語（そのページを訪れる一般的な訪問者が知っていると思われるもの） Uppercase.yml の単語と頭字語のリストに頭字語を追加します。
頭字語 (そのページの平均的な訪問者は知らないでしょう)初めて頭字語を使用するときは、頭字語を完全に書き出し、その後に頭字語を括弧で囲みます。それ以降に使用する場合は、頭字語のみを単独で使用します。例：This feature uses the File Transfer Protocol (FTP). FTP is....
製品名またはサービス名の正しい大文字表記 Uppercase.yml の単語と頭字語のリストに名前を追加してください。
コマンド、変数、コード、または類似のものバックスティックかコードブロックに入れてください。例えばUse `FALSE` as the variable value.
サードパーティ製品のUIテキストそれを避けるように文章を書き直すか、ベール例外コードをインラインで追加してください。

ヴェイルの可読性スコア

ReadingLevel.ymlでは、文書の読みやすさを判定するために、Flesch-Kincaid グレード・レベル・テストを導入しています。

一般的なガイドラインとして、スコアが低ければ低いほど、読みやすい文書であることを示します。たとえば、変更前は12 、変更後は9 、読みやすさが繰り返し改善されていることを示します。スコアは厳密な科学ではありませんが、ページの一般的な複雑さのレベルを示すためのものです。

読みやすさのスコアは、文ごとの単語数と単語ごとの音節数に基づいて計算されます。詳しくは、Valeのドキュメントをご覧ください。

新しいベールルールを追加するタイミング

スタイルガイドのルールごとにベールのルールを追加したくなります。しかし、ベールのルールを作成し、実施する労力と、それが生み出すノイズに留意すべきです。

一般的には、以下のガイドラインに従ってください：

  • エラーレベル・ベイル・ルールを追加する場合、ルールを追加する前に、ドキュメントに記載されている既存のイシューを修正する必要があります。

    1回のマージリクエストで修正するイシューが多すぎる場合は、warning レベルでルールを追加します。その後、後続のマージリクエストで既存のイシューを修正してください。イシューが修正されたら、ルールをerror に昇格させます。

  • 警告レベルまたは提案レベルのルールを追加する場合は、次のことを考慮してください：

    • ヴェイルの出力にどれだけの警告またはサジェスチョンが追加されるか。追加される警告の数が大きい場合、ルールが広すぎる可能性があります。

    • 作成者が、文脈上許容されるからといって、それを無視することがどれだけあるか。ルールが主観的すぎる場合、適切に実施することができず、不必要な追加警告が発生します。

    • GitLab UIのマージリクエストの差分に表示するのが適切かどうか。そのルールをマージリクエストに直接実装するのが難しい場合 (例えば、ページのリファクタリングが必要な場合)、提案レベルに設定してローカルエディタにのみ表示するようにしましょう。

リンターのインストール

最低限、markdownlintと Valeをインストールして、ビルドパイプラインで実行されるチェックに合わせます。

これらのツールはコードエディタとインテグレーションできます。

markdownlintのインストール

markdownlint を実行するには、markdownlint-cli またはmarkdownlint-cli2 のどちらかをインストールします。

markdownlint-cli をインストールするには、以下を実行してください：

yarn global add markdownlint-cli

markdownlint-cli2 をインストールするには、以下を実行してください：

yarn global add markdownlint-cli2

image:docs-lint-markdown をビルドする際には、markdownlint-cli またはmarkdownlint-cli2 で使用されているバージョン (variables: のセクションを参照) をインストールする必要があります。

ベールをインストール

vale をインストールします：

  • asdfを使用している場合はasdf-vale プラグイン をインストールします。.tool-versions ファイルがある GitLab プロジェクトをチェックアウトしてください（例）：

     asdf plugin add vale && asdf install vale

  • パッケージマネージャ：

    • macOSbrew を使用し、brew install vale を実行します。
    • Linuxの場合は、ディストリビューションのパッケージ・マネージャーまたはリリースされたバイナリを使用してください。

リンターの更新

CI/CDパイプラインで使われるリンタと同じバージョンのリンタを使うことが、私たちが使うリントルールとの互換性を最大限に保つために望ましいです。

GitLabプロジェクトで使われているmarkdownlint-cli (またはmarkdownlint-cli2)とvale のバージョンに合わせるには、以下を参照してください：

  • asdf で管理されているプロジェクトの場合、プロジェクト内の.tool-versions ファイル。例えば、gitlab プロジェクト](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.tool-versions) の[.tool-versions ファイル。
  • CI/CD 用のこれらのツールを含むimage:docs-lint-markdown Docker イメージを構築する際に使用されるバージョン（variables: セクションを参照） 。

これらの2つの場所に設定されたバージョンは同じでなければなりません。

ツールバージョンコマンド追加情報
markdownlint-cli最新のyarn global add markdownlint-cliなし
markdownlint-cli2最新のyarn global add markdownlint-cli2なし
markdownlint-cli特定yarn global add markdownlint-cli@0.35.0 @ は特定のバージョンを示し、この例ではツールをバージョン0.35.0 に更新しています。
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専用です。

エディタの設定

エディタでリンターを使うと、コマンドラインからコマンドを実行するよりも便利です。

エディタでmarkdownlintを設定するには、以下のいずれかをインストールしてください：

エディタで Vale を設定するには、以下のいずれかをインストールしてください：

  • Sublime TextSublimeLinter-vale パッケージ.
  • Visual Studio CodeChrisChinchilla.vale-vscode 拡張.アラートのサブセットのみを表示するようにプラグインを設定できます。
  • VimALE プラグイン。
  • JetBrains IDEs - プラグインは存在しませんが、このイシューコメントに外部ツールの設定のヒントが含まれています。

  • EmacsFlycheck拡張。これにはいくつかの設定が必要です：

    • Flycheck markdownlint-cli は内部でサポートしていますが、プロジェクトディレクトリのベースにある.markdownlint.yml を指定する必要があります。.dir-locals.el ：
     ;; Place this code in a file called `.dir-locals.el` at the root of the gitlab project.
 ((markdown-mode . ((flycheck-markdown-markdownlint-cli-config . ".markdownlint.yml"))))
    • ValeでFlycheckを動作させるための最小限の設定は次のようになります：
     (flycheck-define-checker vale
   "A checker for prose"
   :command ("vale" "--output" "line" "--no-wrap"
             source)
   :standard-input nil
   :error-patterns
     ((error line-start (file-name) ":" line ":" column ":" (id (one-or-more (not (any ":")))) ":" (message)   line-end))
   :modes (markdown-mode org-mode text-mode)
   :next-checkers ((t . markdown-markdownlint-cli))
 )
   
 (add-to-list 'flycheck-checkers 'vale)

    この設定では、markdownlint チェッカーは、定義されたvale チェッカーの「次」のチェッカーとして設定されます。このカスタムValeチェッカーを有効にすると、Valeとmarkdownlintの両方からエラーリンティングが行われます。

プリプッシュフックの設定

Gitpre-push フックを使うと、Git ユーザーは次のことができるようになります：

  • ブランチをプッシュする前にテストやその他の処理を実行します。
  • これらのテストで失敗した場合は、ブランチをプッシュしないようにしましょう。

lefthook は Git フックマネージャで、Git フックの設定やインストール、削除をよりシンプルにします。

lefthook の設定はgitlab プロジェクトのlefthook.yml ファイルで行います。

lefthook をドキュメントのリンティング用に設定するには、Pre-push static analysisを参照してください。

プッシュ時にValeの警告を表示

デフォルトでは、lefthook はブランチに変更をプッシュする際に Vale エラーのみを表示します。デフォルトのブランチには Vale のエラーはないので、ここに表示されるエラーはブランチへのコミットによって発生したものです。

ブランチへのプッシュ時に Vale の警告も表示するには、内部環境変数VALE_WARNINGS=true を設定します。

プッシュ時に Vale の警告を表示するようにすると、ドキュメント群を改善できます：

  • コミット時に発生する可能性のある警告を検出します。
  • 技術的負債を減らすために解決できる、ページ内にすでに存在する警告を検出します。

これらの警告は

  • プッシュを止めないでください。
  • パイプラインの断絶を招かないように。
  • コミットによって導入された警告だけでなく、ファイルのすべての警告を含めます。

プッシュ時に Vale 警告を有効にするには

  • シェルの設定にVALE_WARNINGS=true を追加してください。

  • 手動では、lefthook の呼び出しの前にVALE_WARNINGS=true を追加します：

     VALE_WARNINGS=true bundle exec lefthook run pre-push

Valeの警告を表示するようにエディタを設定することもできます。

ベール警告のサブセットを表示

ファイルを表示するときに、Valeアラートのサブセットのみを表示するようにVisual Studio Codeを設定できます：

  1. 環境設定 > 設定 > 拡張機能 > Vale.
  2. Vale CLI: Min Alert Level（最小アラートレベル）]で、ファイルに表示する最小アラートレベルを選択します。

コマンドラインからValeを実行するときにValeアラートのサブセットのみを表示するには、error 、warning 、またはsuggestionを受け付ける--minAlertLevel フラグを使用します。 必要に応じて、--config と組み合わせてプロジェクト内の設定ファイルを指定します：

vale --config .vale.ini --minAlertLevel error doc/**/*.md

フラグを省略すると、suggestion レベルのアラートを含むすべてのアラートが表示されます。

ベールテストの無効化

ドキュメントの任意の部分について、特定のベール・リンティング・ルールまたはすべてのベール・リンティング・ルールを無効にすることができます：

  • 特定のルールを無効にするには、<!-- vale gitlab.rulename = NO --> タグをテキストの前に追加し、<!-- vale gitlab.rulename = YES --> タグをテキストの後に追加します。rulename はGitLab stylesディレクトリにあるテストのファイル名に置き換えてください。
  • すべての Vale linting ルールを無効にするには、<!-- vale off --> タグをテキストの前に、<!-- vale on --> タグをテキストの後に追加します。

可能な限り、問題のあるルールと行だけを除外してください。

詳しくは、Valeのドキュメントを参照してください。

markdownlintテストの無効化

すべてのmarkdownlintルールを無効にするには、テキストの前に<!-- markdownlint-disable --> タグを、テキストの後に<!-- markdownlint-enable --> タグを追加します。

特定のルールだけを無効にするには、<!-- markdownlint-disable MD044 --> や<!-- markdownlint-enable MD044 --> のように、タグにルール番号を追加します。

可能な限り、問題のある行だけを除外してください。