GitLab Runnerのレビュー

この文書には、GitLab Runnerプロジェクトのレビュアーに対するルールと提案が書かれています。

テストカバレッジレポートのレビュー

GitLab Runnerプロジェクトにはたくさんのコードがあります。 残念ながら、コードカバレッジは包括的ではありません。 現在（2019年初め）、カバレッジは~55%のレベルです。

レガシーコードにテストを追加するのは大変な作業ですが、プロジェクトに追加される新しい コードが、良いテストカバレッジを持っていることを保証しなければなりません。 コードレビュアーは、カバレッジレポートを見て、新しいコードがカバーされていることを確認するよう 奨励されます。

新しいコードに対しては、可能な限り多くのテストカバレッジを目指すべきです。 特定の変更に必要なカバレッジのレベルを定義することは、レビュアーの判断に委ねられます。 100%のカバレッジを達成するのが簡単な場合もあれば、20%のカバレッジでコードを追加するのが現実的で、最も重要なことが確実にテストされる場合もあります。 レビュアーへ - 賢く選択してください :)

技術的な話に戻りますが…。

Runner の CI パイプラインは、通常モード (count) とレースモード (atomic) で実行されたテストのカバレッジレポートを HTML 形式で提供してくれます。

テストカバレッジレポートを見ることができる場所は 2 つあります：

S3からのテストカバレッジレポート

このレポートの有効期限は長期ですが、gitlab-runners-download S3 バケットを使用しているため、https://gitlab.com/gitlab-org/gitlab-runnerに直接貢献した場合のみ利用可能です。また、master ブランチから開始されたすべてのジョブ (つまり、ほとんどがマージリクエストのマージ) と、すべてのタグ付きリリースで利用可能です。

レポートを開くには

  1. レビューしたい変更に関連するパイプラインを見つけます。 それはマージリクエストの最新のパイプラインかもしれませんし、タグのパイプラインかもしれません。 例えば、https://gitlab.com/gitlab-org/gitlab-runner/pipelines/48686952、v11.8.0 バージョンのレビュアーがリリースされました。

  2. パイプラインで、stable S3 (タグ付きリリースの場合)、bleeding edge S3 (master および RC タグ付きリリースの場合)、development S3 (通常のコミットの場合) のジョブを見つけ、release のステージに存在するはずです。この例のパイプラインでは、https://gitlab.com/gitlab-org/gitlab-runner/-/jobs/165757556となります。

  3. ジョブのログの最後に、次のような行があるはずです： 

    ==> Download index file: https://gitlab-runner-downloads.s3.amazonaws.com/latest/index.html

    というのも、このジョブがトリガーされ、v11.8.0 もlatest リリースlatestされると、バージョンlatest バケツへのリンクがlatest表示されるからです。latest の問題は、新しい安定版/パッチ版がリリースされると、そこにあるコンテンツが変わってしまうことです。

    各パイプラインはまた、特定の参照（ブランチ名またはタグ名）に対するデプロイを作成します。 上記の数行で確認できます： 

    ==> Download index file: https://gitlab-runner-downloads.s3.amazonaws.com/v11.8.0/index.html

    master ブランチから開始されたbleeding edge S3 ジョブの場合、URL はhttps://gitlab-runner-downloads.s3.amazonaws.com/master/index.htmlのようになります (これは明らかに時間経過とともに変化します)。また、RC タグから開始されたジョブの場合、URL はhttps://gitlab-runner-downloads.s3.amazonaws.com/v11.8.0-rc1/index.htmlのようになります。通常のコミットから開始されたdevelopment S3 ジョブの場合、URL はhttps://gitlab-runner-downloads.s3.amazonaws.com/mask-trace/index.htmlのようになります (ほとんどの場合、マージリクエストの内部で追跡されます)。この場合、mask-trace はマージリクエストのソースとして使用されたブランチの名前です。

  4. ジョブのログから収集したS3リンクを開いてください。例に従って、https://gitlab-runner-downloads.s3.amazonaws.com/v11.8.0/index.html 。リリースの一部として公開されたいくつかのファイルを見ることができます。coverage/ ディレクトリの内容に興味があります。

    このディレクトリには、.race. がファイル名の一部となっているファイルが 3 つと、.regular. がファイル名の一部となっている同様のファイルが 3 つあります。これらのファイルは、go test コマンドをカバレッジオプション付きで実行したときの追跡出力です。.race. ファイルには、-race フラグ付きで開始したテストのソースとレポーターが含まれており、.regular. ファイルには、このオプションなしで開始したテストのソースとレポーターが含まれています。

    詳細に興味のある方は、-race テストはatomic カバレッジ・モードを使用し、標準テストはcount カバレッジ・モードを使用しています。

    coverage/coverprofile.regular.html .race. テストはレースコンディションの状況で失敗することがあり (これがテストを実行する理由です)、 現在、いくつかのテストが常に失敗しています。 これは、カバレッジプロファイルが完全でない可能性があることを意味します。

    .regular. テストは、コードの内部で何がテストされているのか、その全体像を教えてくれるはずです。 これを調べるには、次のようにします：

  5. 指名されたレポートのHTMLページを開いてください。 上記のように、coverage/coverprofile.regular.html が私たちの関心事なので、最初の例を使って、https://gitlab-runner-downloads.s3.amazonaws.com/v11.8.0/coverage/coverprofile.regular.html#file0ファイルを開いてください。

  6. この時点で、テストカバレッジの詳細を表示するファイルブラウザが表示されます。 上部にあるドロップダウン選択で、レビューした修正に関連するファイルを選択し、カバレッジがどのように変化しているかをチェックすることができます。

ジョブアーティファクトからのテストカバレッジレポート

上に書いたように、S3バケットにホストされたレポートは、https://gitlab.com/gitlab-org/gitlab-runner プロジェクトから直接開始されたパイプラインにのみ利用可能です。しかし、レビュアーが扱っている貢献の多くは、コミュニティフォークからの貢献です。

この場合、.regular. と.race. の2種類のレポートが、まったく同じ方法で生成されます。唯一の違いは、レポートがある場所とその寿命です。 レポートはジョブのアーティファクトとして保存され、次にリリースステージに渡すことができます)。 レポートには7日間の有効期限が設定されています。 そのため、1週間以上前にパイプラインを実行した変更をレビューする場合、レポートは利用できません。 しかし、コードに変更がなくても、新しいパイプラインを実行すれば、問題は解決されます。

マージリクエストのコードカバレッジレポートを表示します：

  1. マージリクエストの［概要］タブで、パイプライン結果の下にある［公開アーティファクトを表示］をクリックして、セクションを展開します。
  2. コード・カバレッジをクリックします。

  3. アーティファクトブラウザを使用して、out/coverage/ディレクトリに移動します。例えば、https://gitlab.com/gitlab-org/gitlab-runner/-/jobs/172824578/artifacts/browse/out/coverage/。このディレクトリには、S3 カバレッジレポート戦略で説明したように、3つの.race. ファイルと3つの.regular. ファイルの合計6つのファイルが常に含まれます。

    変更のレビューでは、.regular. HTMLレポート（coverprofile.regular.html ファイル）を見ることに主に興味があります。ご覧のように、すべてのファイルは外部リンクとして表示されます。この例では、https://gitlab.com/gitlab-org/gitlab-runner/-/jobs/172824578/artifacts/file/out/coverage/coverprofile.regular.htmlを開き、レポートが保存されているhttps://gitlab-org.gitlab.io/-/gitlab-runner/-/jobs/172824578/artifacts/out/coverage/coverprofile.regular.htmlにリダイレクトします。

  4. この時点で、S3ソースで見たのと同じカバレッジの詳細がファイルブラウザに表示されます。 同じことができます。 唯一の違いは、最大7日間で消えるということです。

マージリクエストタイトルのレビュー

私たちはマージリクエストのタイトルからCHANGELOG.md エントリを生成するため、タイトルが有効で有益であることを確認することは、レビュアーとメンテナーの責任の一部です。

マージリクエストをマージする前に、タイトルをチェックし、CHANGELOG.md ファイルでわかりにくいと思われる場合は更新してください。変更履歴にはこの一行しかなく、マージリクエストの説明、議論、差分など、より多くの文脈を提供するものがないことに留意してください。

例えば、https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/1812 ：

  • yml to yaml - これはオリジナルのタイトルで、私たちのスクリプトで変更履歴に追加されました、
  • Fix values.yaml file name in documentation - これは変更履歴で更新したものです。

ランナー管理者が新しいバージョンにアップデートする前に変更履歴をレビューした場合、yml to yaml 。アップデートの背後にあるリスク、実装された動作の変更、追加された新しい動作や機能を示していますか？ マージリクエストとそのタイトルをレビューする際には、これらの質問に留意してください。

投稿者は上記の情報を知らないかもしれませんし、そのタイトルが私たちの要件と一致しないかもしれません。 このことについて投稿者を教育するようにしてください。 最終的には、マージリクエストがマージされる前にタイトルを確認し、更新するのはあなたの責任です。

概要

レビュアーへ、剣を手に入れたのですから、ドラゴンと戦ってください！