GitLab Runnerのレビュー

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

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

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

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

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

技術的な詳細に戻ります…

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

.race と.regular をファイル名の一部として含む二種類のレポーターがあります。これらのファイルは、カバレッジ・オプションを指定して実行されたgo test コマンドの追跡出力です。.race. ファイルには、-race フラグとともに開始されたテストのソースとレポーターが含まれ、.regular. ファイルには、このオプションを指定せずに開始されたテストのソースとレポーターが含まれます。

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

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

.regular. のテストは、コードの内部でテストされていることの全容を示してくれるはずです。

マージリクエストのコードカバレッジレポートを見るには：

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

  2. コードカバレッジをクリックします。

  3. アーティファクト・ブラウザを使用して、out/coverage/ ディレクトリに移動します。例えば、https://gitlab.com/gitlab-org/gitlab-runner/-/jobs/172824578/artifacts/browse/out/coverage/ 。このディレクトリには、常に 6 つのファイル（3 つの.race. ファイルと 3 つの.regular. ファイル）が含まれます。

    変更のレビュアーとしては、主に.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 にリダイレクトします。

カバレッジデータはマージリクエストUIにも表示されるはずです。

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

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

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

例として、https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/1812 を見て比較してください：

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

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

投稿者は上記の情報を知らないかもしれませんし、投稿者のタイトルが私たちの要求と一致しないかもしれません。このことについて投稿者を教育するようにしてください。

最終的に、マージリクエストがマージされる前にタイトルを確認し、更新するのはあなたの責任です。

マージリクエストラベルのレビュー

異なるグループに変更ログエントリーをグループ化し、個々のエントリーのいくつかの特別な機能を定義するために、マージリクエストに割り当てられたラベルを使用します。

変更ログを生成するために、私たちは独自のChangelog ジェネレーターを使っています。このツールは GitLab Runner リポジトリにコミットされた設定ファイルを使用しています。

レビュアーがChangelogジェネレーターについて知っておくべき重要なことがいくつかあります：

  • GitLab Changelog はlabel_matchers が定義された順番にマージリクエストラベルを分析します。最初にマッチしたスコープが分析されたマージリクエストに使われます。

    たとえば、2つのマージリクエストがあり、1つ目はsecurity bug、2つ目はラベルのみを含む bugもので、3つのマッチャーがこの順番で定義されていたとします：[security, bug] -> [security] -> [bug]そして、最初のマージリクエストは[security, bug] によってマッチされたスコープに追加され (つまり、リスト上で最初に定義されたスコープ)、2番目のマージリクエストは[bug] によってマッチされたスコープに追加されます (つまり、リスト上で最後に定義されたスコープ)。

  • で定義されたラベルでラベル付けされたマージリクエストは、authorship_labels 作成者のユーザー名を最後に追加して変更履歴に追加さ authorship_labelsれます。このようにマークされるためには、authorship_labels すべての authorship_labelsラベルがマージリクエストに追加される必要があります。

  • で定義されたラベルでラベル付けされたマージリクエストはskip_changelog_labels 変更ログでスキップさ skip_changelog_labelsれます。スキップされるためにはskip_changelog_labels すべての skip_changelog_labelsラベルがマージリクエストに追加される必要があります。

  • 定義されたlabel_matchers のどれにもマッチしないマージリクエストはOther changes スコープバケツに追加されます。

これらのことを念頭に置いて、マージリクエストをマージするときは以下のルールに従ってください：

  • GitLab Runner やそのパーツのディストリビューション方法に関連するマージリクエストには、runner-distribution のラベルを付けてください。

  • セキュリティに関わるマージリクエストは、それが新機能であろうとバグフィックスであろうと、security 。feature::addition でないマージリクエストはすべてセキュリティスコープに追加されます。

  • バグ修正のマージリクエストにはbug のラベルをつけてください。

  • ドキュメントの更新のみ、または明示的なバグ修正ではないほとんどのマージリクエストでは、feature:: またはtooling:: ラベルのいずれかが追加されていることを確認してください。そうすることで、変更履歴のエントリを適切に並べ替えることができます。

  • documentation ラベルはテクニカルライティングのレビューが行われたときに自動的に追加されます。マージリクエストがドキュメント以上のものを更新する場合でもです。もしマージリクエストがラベルのみを持ち documentation、label_matchers にマッチする他のラベルを持たない場合、そのマージリクエストがドキュメントのみを更新していることを再確認してください。そうでない場合は、追加される変更の種類に一致する特定のラベルのいずれかを使用してください！

  • 同じリリースサイクルでマージされた変更を差し戻す場合、元のマージリクエストと差し戻しリクエストにskip_changelog_labels で定義されたラベルを付けてください。こうすることで、リリースを準備する際にリリースマネージャが行う必要がある手動作業を減らすことができます。同じバージョンで両方のイベントが発生した場合、変更の追加と変更の差し戻しに関するエントリを追加すべきではありません。

    GitLab Runner のすでにリリースされたバージョンにマージされたものをマージリクエストで戻す場合は、正しいスコープラベルを付けてください。その場合、変更履歴に差し戻しのマークを付けます。

  • また、エンジニアリングメトリクスのデータ分類のページもご覧ください。

要約

レビュアーへ、剣を手に入れましたね。さあ、ドラゴンと戦ってください！