マージリクエストワークフロー

GitLabのコードやテスト、ドキュメントの修正や改善など、みなさんからのマージリクエストを歓迎します。特にコミュニティ貢献に向いているイシューにはSeeking community contributions というラベルがついていますが、どのイシューにも自由に貢献することができます。

イシューからの作業

イシューを見つけた場合、可能であれば修正または改善とテストをマージリクエストとして提出してください。

ラベル付けされていない新機能を追加したい場合は、まずイシューを作成し (まだなければ)、Seeking community contributionsとしてラベル付けしてほしいというコメントを残すのがベストです。機能提案のセクションをご覧ください。

イシューを修正する方法はわからないけれども、そのイシューを明らかにするテストは書けるという場合は、それも受け付けます。一般的に、リグレッションテストを含むバグ修正は素早くマージされます。適切なテストがない新機能は、フィードバックを受け取るのが遅くなるかもしれません。

GitLab 開発（あるいは一般的なウェブ開発）に慣れていない場合は、貢献する方法のセクションを参照して、簡単そうなイシューから始めてみましょう。

マージリクエストの所有権

作業中であっても、現在のマイルストーンにイシューがマークされた場合、GitLabチームメンバーがマージリクエストを引き継ぎ、リリース日までに作業を完了させることができます。

コントリビューターが提出されたマージリクエストに対してもはやアクティブに作業していない場合、私たちはできます：

私たちはこの決定を、その変更が製品ビジョンにとってどれほど重要であるかに基づいて行います。マージリクエストコーチがマージリクエストを終了する場合、~coach will finish ラベルを割り当てます。

チームメンバーがコミュニティの貢献者をピックアップした場合、作成者のクレジットを記載した変更履歴を追加し、オプションで MR 内のコミットの少なくともひとつに作成者を記載します。

貢献者のためのマージリクエストガイドライン

貢献プロセスのウォークスルーについては、チュートリアルをご覧ください：GitLab に貢献する.

ベストプラクティス

  • もしその変更が些細なものでない場合は、プロダクトマネージャーやチームのメンバーとディスカッションを始めることをお勧めします。レビューのためにコードを提出する前に、MRにタグ付けすることでこれを行うことができます。チームメンバーと話すことは、設計を決定する際に役立ちます。変更の背後にある意図を伝えることは、マージリクエストレビューの迅速化にも役立ちます。

  • 本番環境の可用性に影響を与える可能性がある場合は、コードを機能フラグの後ろに置くことを検討してください。よくわからないですか？機能フラグを使うタイミングを読んでください。

  • マージリクエストに対する素早いフィードバックが必要な場合は、コアチームの誰かかマージリクエストコーチに遠慮なく言ってください。コードをレビューしてもらうときやマージリクエストをレビューするときは、コードレビューガイドラインを念頭に置いてください。また、あなたのコードがデータベースにも変更を加えたり、高価なクエリを実行したりする場合は、データベースレビューガイドラインを確認してください。

シンプルに

小さな反復で生きてください。1回のMRでの変更量はできるだけ少なくしてください。もし大きな機能を貢献したいのであれば、実行可能な最小限の変更とは何かをよく考えてください。機能を2つの小さなMRに分割できますか？バックエンド/APIコードだけを提出できますか？非常にシンプルなUIから始められますか？リファクタリングの一部だけを行うことはできますか？

最小限のコミットログを持つことよりも、より簡単にレビュアーできる小さなMRの方が、GitLabにとってより重要な、より高いコード品質につながります。MR が小さければ小さいほど、すぐにマージされる可能性が高くなります。その後、さらに MR を送って機能を強化・拡張することができます。KubernetesチームによるHow to get faster PR reviewsのドキュメントにも、これに関する素晴らしいポイントがいくつかあります。

コミットメッセージガイドライン

コミットメッセージは以下のガイドラインに従うべきです。その理由は、Chris Beams がHow to Write a Git Commit Message で説明しているからです：

  • コミットの件名と本文は空行で区切らなければなりません。
  • コミット件名は大文字で始めなければなりません。
  • コミット件名は72文字以内でなければなりません。
  • コミット件名はピリオドで終わってはいけません。
  • コミット本文は1行に72文字を超えてはいけません。
  • コミットの件名や本文に絵文字を含めてはいけません。
  • 少なくとも3つのファイルにまたがる30行以上の変更を行うコミットは、コミット本文にその変更を記述してください。
  • イシュー、マイルストーン、マージリクエストの URL は、GitLab の外ではプレーンテキストで表示されるので、短い参照ではなく完全な URL を使いましょう。
  • マージリクエストには 10 件以上のコミットメッセージを含めないでください。
  • コミット件名には少なくとも3つの単語を含める必要があります。

重要な注意事項です：

  • ガイドラインを満たしていない場合、MRはデンジャーチェックを通過しない可能性があります。
  • マージリクエストに “Applied suggestion to X files “というコミットが含まれている場合、Squashを有効にしてマージすることを検討してください。
  • [prefix] 、prefix: のようなプレフィックスをつけることができます（メッセージ自体が大文字であれば、すべて小文字でもかまいません）。例えば、danger: Improve Danger behavior と[API] Improve the labels endpoint は有効なコミットメッセージです。

これらの標準が重要な理由

  1. これらのガイドラインに従った一貫したコミットメッセージは、履歴をより読みやすくします。
  2. 標準的なコミットメッセージを簡潔にまとめることで、デプロイや~"master:broken" の変更点をすばやく特定することができます。

コミットメッセージテンプレート

上記を具体化した、あなたのマシンで使用できるコミットメッセージテンプレートの例（テンプレートの適用方法のガイド）：

# (If applied, this commit will...) <subject>        (Max 72 characters)
# |<----          Using a Maximum Of 72 Characters                ---->|


# Explain why this change is being made
# |<----   Try To Limit Each Line to a Maximum Of 72 Characters   ---->|

# Provide links or keys to any relevant tickets, articles or other resources
# Use issues and merge requests' full URLs instead of short references,
# as they are displayed as plain text outside of GitLab

# --- COMMIT END ---
# --------------------
# Remember to
#    Capitalize the subject line
#    Use the imperative mood in the subject line
#    Do not end the subject line with a period
#    Subject must contain at least 3 words
#    Separate subject from body with a blank line
#    Commits that change 30 or more lines across at least 3 files should
#    describe these changes in the commit body
#    Do not use Emojis
#    Use the body to explain what and why vs. how
#    Can use multiple lines with "-" for bullet points in body
#    For more information: https://cbea.ms/git-commit/
# --------------------

貢献者の受け入れ基準

あなたのマージリクエストが承認されるように、以下の貢献受諾基準を満たしていることを確認してください：

  1. 変更ができるだけ小さいこと。
  2. マージリクエストが500以上の変更を含む場合：
    • 理由を説明してください
    • メンテナーについての言及
  3. 大きな変更について言及してください。
  4. 適切なテストを含み、すべてのテストがパスするようにしてください（既存のコードのバグを暴露するテストが含まれていない限り）。たとえそのクラスが機能テストのような高いレベルで実施されるものであったとしてもです。
    • もし CI のビルドが失敗し、あなたの貢献とは無関係だと思われる場合は、失敗した CI ジョブを再スタートしてみたり、失敗を解決するかもしれないアップデートを取り込むためにターゲットブランチをリベースしてみたり、まだ修正されていない場合は開発者にテストの修正を手伝ってもらったりすることができます。
  5. MR には論理的に整理されたコミットがいくつか含まれているか、コミットの破棄が有効になっています。
  6. 変更は問題なくマージできます。そうでなければ、デフォルトブランチを MR ブランチにマージしなければなりません。
  7. 特定のイシューが修正されたか、特定の機能が実装されただけです。イシューや機能ごとにマージリクエストを送ってください。
  8. マイグレーションは、失敗時の再試行を助けるために、1つのこと (たとえば、テーブルの作成、新しいテーブルへのデータの移動、古いテーブルの削除) だけを行うようにしてください。
  9. 他のユーザーが恩恵を受けられるような機能をコンテナに含んでいること。
  10. 設定オプションや設定オプションは、将来の変更の作成とテストを複雑にするので、追加しません。
  11. 変更はパフォーマンスを低下させません：
    • 多大なオーバーヘッドを必要とするエンドポイントの繰り返しポーリングは避けてください。
    • SQL ログまたはQueryRecorderを介して N+1 クエリをチェックします。
    • ファイルシステムへの繰り返しアクセスを避けてください。
    • リアルタイム機能をサポートするために必要であれば、ETagキャッシングとポーリングを使用してください。
  12. マージリクエストが新しいライブラリ（gemsやJavaScriptライブラリなど）を追加する場合、それらはライセンスガイドラインに準拠する必要があります。”license-finder “テストがDependencies that need approval エラーで失敗した場合のヘルプについては、これらの説明を参照してください。また、レビュアーに新しいライブラリの存在を知らせ、それが必要な理由を説明してください。
  13. マージリクエストは、以下の GitLab の完了の定義を満たしています。

done の定義

GitLabに貢献するなら、変更にはコード以上のものが含まれることを知っておいてください。私たちは、次のような完了の定義を使っています。完了の定義に達するには、マージリクエストはリグレッションを発生させず、これらの基準をすべて満たす必要があります：

リグレッションが発生した場合は、変更を元に戻してください。これらの要件をすべて満たしていることを確認するまでは、あなたの貢献は不完全です。

機能性

  1. 必要に応じてコメントされた、動作するきれいなコード。
  2. 変更は、遠大な作業の影響を抑えるために評価されます。
  3. パフォーマンス・ガイドラインに従っています。
  4. セキュアコーディングガイドラインに準拠しています。
  5. 申請と料金制限のガイドラインに従っています。
  6. /doc ディレクトリに記載。
  7. MR がシェル・コマンドを実行したり、ファイルを読み込んだり開いたり、ディスク上のファイルへのパスを処理したりするコードに触れる場合は、シェル・コマンドのガイドラインに従っていることを確認してください。
  8. コードの変更には、観測可能なインスツルメンテーションを含める必要があります。
  9. あなたのコードがファイルストレージを扱う必要がある場合は、アップロードのドキュメントを参照してください。
  10. マージリクエストに 1 つ以上のマイグレーションが追加された場合、MR のレビューが行われる前に、必ず新しいデータベースですべてのマイグレーションを実行してください。レビューによって MR に大きな変更が生じる場合は、レビュー完了後にマイグレーションを再度実行してください。

  11. マージリクエストが既存のモデルに新しい検証を追加する場合は、データ処理に後方互換性があることを確認します：

    • 既存の行が変更によって影響を受けないことを確認するために、既存の行をチェックするデータベースクエリを実行する支援を#database Slack チャンネルで求めてください。
    • ロールアウトのステップに従って徐々にロールアウトされる機能フラグで必要な検証を追加します。

    このマージリクエストが緊急である場合、既存の行のレビューをマージリクエストの即時フォローアップタスクとして含めるべきかどうか、コードオーナーが最終判断を下すべきです。

    note
    自己管理インスタンス上の顧客のデータについて知る方法はありませんので、マージリクエストに伴うデータへの影響に留意してください。

  12. セルフマネージド機能とアップグレードパスを考慮してください。変更は両方を考慮する必要があります：

    • 自己管理の可用性のために追加作業が必要な場合、および
    • GitLabのバージョンをアップグレードする際に必要な停止が必要な変更である場合。

    GitLabのコード変更がバックグラウンドマイグレーションが既に完了していることに依存している場合、アップグレードストップが要求されることがあります。アップグレードストップが必要な変更は、次のメジャーリリースに持ち越すか、やむを得ない場合は少なくとも3マイルストーン前に通知するのが理想的です。

テスト

  1. ユニットテスト、インテグレーションテスト、システムテストはすべてCIサーバー上で行われます。
  2. ピアメンバテストはオプションですが、変更のリスクが高い場合に推奨されます。これには、変更が広範囲に及ぶ場合や、セキュリティ上重要なコンポーネントの場合などが含まれます。
  3. リグレッションとバグは、イシューが再び発生するリスクを低減するテストでカバーします。
  4. Capybara を使うテストについては、信頼性の高い非同期インテグレーションテストの書き方を読んでください。
  5. 必要に応じて、ブラックボックステスト/エンドツーエンドテストを追加します。質問があれば品質チームに連絡してください。
  6. 可能であれば、また適切であれば、変更はレビューアプリでテストされます。
  7. 機能フラグの影響を受けるコードは、機能フラグが有効な場合と無効な場合の自動テストでカバーされるか、ピアメンバーテストの一部として、またはロールアウト計画の一部として、両方の状態がテストされます。
  8. マージリクエストが1つ以上のマイグレーションを追加する場合、より複雑なマイグレーション用のテストを書いてください。

UI の変更

  1. GitLabデザインシステムPajamasの利用可能なコンポーネントを使用します。
  2. UIを変更した場合、MRは変更前と 変更後のスクリーンショットを含める必要があります。
  3. MR が CSS クラスを変更した場合、影響を受けるページのリストを添付してください。これは、grep css-class ./app -R を実行することで見つけることができます。

変更内容

  1. 貢献することの関連性を説明する明確なタイトルと説明。
  2. 説明には、あなたが行った変更をレビュアーが確実に閲覧できるようにするために必要な手順や設定を含みます (たとえば、機能フラグに関する情報を含みます)。
  3. 必要であれば、Changelogエントリを追加してください。
  4. GitLab をソースからインストールする際に追加の手順が必要になる変更がマージリクエストに含まれている場合は、同じマージリクエストでdoc/install/installation.md に追加してください。
  5. もしあなたのマージリクエストが、GitLabをソースからアップグレードするときに追加の手順を必要とする変更を導入するなら、同じマージリクエストのdoc/update/upgrading_from_source.md 。これらの指示がバージョンに固有のものである場合は、”バージョン固有のアップグレード手順” セクションに追加してください。

承認者

  1. MR受入チェックリストは、MRで確認された通りです。
  2. 貢献者がデフォルト設定を変更したり、新しい設定を導入したりする場合は、インフラストラクチャー部門に通知するために、インフラストラクチャーの課題追跡でイシューを作成してください。
  3. 合意されたロールアウト計画。
  4. 関連するレビュアーによってレビューされ、可用性、レグレッション、セキュリティに関するすべての懸念にアドレスされていること。ドキュメントレビューはできるだけ早く行われるべきですが、マージリクエストをブロックすべきではありません。
  5. マージリクエストには少なくとも1つの承認が必要ですが、変更内容によってはさらに承認者が必要になる場合があります。承認者ガイドラインを参照してください。
    • 特定の承認者を選択する必要はありませんが、特定の人にマージリクエストを承認してもらいたい場合は選択できます。
  6. プロジェクトのメンテナーによってマージされました。

本番使用

以下の項目はマージリクエストがマージされた後にチェックされます：

  1. 可能であれば、本番環境で変更を実装する前にステージで動作することを確認します。
  2. 貢献がデプロイされた後、新たなSentryエラーが発生せず、本番環境で動作することを確認。
  3. ロールアウト計画が完了したことを確認。
  4. 変更にパフォーマンスリスクがある場合、変更前後のシステムのパフォーマンスを分析したこと。
  5. マージリクエストが機能フラグ、プロジェクト単位またはグループ単位の有効化、およびステージドロールアウトを使用している場合：
    • GitLab プロジェクトでの作業を確認済み。
    • 追加されたすべてのプロジェクトの各ステージで動作することを確認。
  6. 該当する場合はリリース記事に追記。
  7. 関連する場合、ウェブサイトに追加。

貢献者に製品チームの承認は必要ありません。

依存関係

GitLabで依存関係を追加する場合（オペレーションシステムのパッケージなど）、以下の更新を検討してください。そして、マージリクエストにそれぞれの適用可能性を記入してください：

  1. リリースのブログ記事に追加したことを書いてください（まだ存在しない場合は作成してください）。
  2. アップグレードガイド
  3. GitLab インストールガイド.
  4. GitLab開発キット.
  5. CI環境の準備。
  6. Omnibusパッケージ作成。
  7. クラウドネイティブのGitLab Dockerfile

インクリメンタルな改善

私たちは、（イシューの有無にかかわらず）インクリメンタルな改善である、以下のような小さな問題を修正するためのエンジニアリング時間を認めています：

  1. 優先順位付けされていないバグ修正（例えば、プロジェクト移動のバナーアラートがあちこちに表示されるなど）
  2. ドキュメントの改善
  3. RuboCop または Code Quality の改善

この分野の作業を追跡するために、マージリクエストに ~"Stuff that should Just Work" とタグ付けしてください。