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

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

作業中であっても、現在のマイルストーンにイシューがマークされた場合、GitLab Inc.のチームメンバーが、リリース日までに作業が完了するようにマージリクエストを引き継ぐことがありますのでご注意ください。

ラベルのない新機能を追加したい場合は、（まだイシューがない場合は）まずイシューを作成し、Accepting Merge Requests。UIも変更する場合は、提案する機能のスクリーンショットやワイヤーフレームを添付してください。

マージリクエストはGitLab.comの適切なプロジェクト（GitLab、GitLab Runner、Omnibus GitLabなど）に提出してください。

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

GitLabの開発を始めるには、GitLab Development Kitをダウンロードし、必要なガイドラインについては開発セクションをご覧ください。

マージリクエストのガイドライン

もし問題を見つけたら、可能であれば修正もしくは改善とテストを添えてマージリクエストを提出してください。 もしあなたが問題の修正方法を知らなくても、問題を明らかにするテストを書けるのであれば、それも受け付けます。 一般的に、リグレッションテストを含むバグ修正は素早くマージされますが、適切なテストがない新機能はフィードバックを受け取るのが遅くなるかもしれません。 マージリクエストのワークフローは以下の通りです：

  1. GitLab.comの個人ネームスペース（またはグループ）にプロジェクトをフォークします。
  2. フォークにfeatureブランチを作成してください（masterから作業しないでください）。
  3. テストとコードを書いてください。
  4. で変更履歴を生成します。bin/changelog
  5. ドキュメントを書く場合は、必ずドキュメントのガイドラインに従ってください。
  6. コミットメッセージのガイドラインに従ってください。
  7. 複数のコミットがある場合は、それらをつぶして論理的にいくつかのコミットにまとめます。ただし、共有ブランチで作業している場合はコミット履歴を変更しないでください。
  8. コミットをフォークの作業ブランチにプッシュします。
  9. メインのGitLabプロジェクトのmaster ブランチにマージリクエスト(MR) 。
    1. マージリクエストには少なくとも1つの承認が必要ですが、変更内容によってはさらに承認者が必要になる場合があります。承認ガイドラインを参照してください。
    2. 特定の承認者を選択する必要はありませんが、どうしても特定の人にマージリクエストを承認してもらいたい場合は選択できます。
  10. MRのタイトルは、あなたが行いたい変更を記述してください。
  11. MRの説明には、変更の理由を書いてください。
    1. コードを貢献する場合、”Description “フィールドにすでに提供されているデフォルトのテンプレートに従って説明を記入してください。
    2. ドキュメントを貢献する場合は、”Choose a template “メニューからDocumentation を選択し、テンプレートに従って説明を記入してください。
    3. Solves #XXX またはCloses #XXX 構文を使用して、マージリクエストが解決するイシューを記述してください。マージリクエストがマージされると、イシューは自動的にクローズされます。
  12. もし許されるなら、関連するマイルストーンとラベルを設定してください。
  13. UIの変更には、GitLabデザインシステムPajamasの利用可能なコンポーネントを使用してください。 MRには、変更前と**変更後のスクリーンショットを添付してください。
  14. grep css-class ./app -RMRがCSSクラスを変更した場合、影響を受けるページのリストを含めてください。
  15. MRがシェルコマンドを実行するコード、ファイルを読み込んだり開いたりするコード、ディスク上のファイルへのパスを処理するコードに触れる場合は、シェルコマンドのガイドラインに従っていることを確認してください。
  16. あなたのコードがディスク上に新しいファイルを作成する場合は、共有ファイルのガイドラインをお読みください。
  17. マージリクエストに 1 つ以上のマイグレーションが追加された場合、MR がレビューされる前に、必ず新しいデータベースですべてのマイグレーションを実行してください。 レビューによって MR に大きな変更が生じた場合は、レビューが完了してからマイグレーションを再度実行してください。
  18. より複雑なマイグレーションのためのテストを書いてください。
  19. マージリクエストはマージリクエストパフォーマンスガイドラインに従わなければなりません。
  20. Capybara を使うテストについては、信頼性の高い非同期インテグレーションテストの書き方を参照ください。
  21. マージリクエストに、GitLabをソースからインストールする際に追加の手順を必要とする変更が含まれている場合は、同じマージリクエストのdoc/install/installation.md 。
  22. GitLabをソースからアップグレードする際に追加の手順を必要とする変更がマージリクエストに含まれている場合は、同じマージリクエストのdoc/update/upgrading_from_source.md 。これらの指示がバージョンに固有のものである場合は、「バージョン固有のアップグレード手順」に追加してください。
  23. マージリクエスト作成者の責任」を読み、遵守してください。
  24. 読む、従う マージリクエストをレビューしてもらいます。

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

シンプルに

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

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

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

コミットメッセージを書くときは、以下のガイドラインに従ってください：

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

ガイドラインを満たしていない場合、MR は危険チェックを通過しません。 詳しくはGit コミットメッセージの書き方を参照ください。

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

# (If applied, this commit will...) <subject> (Max 50 char)
# |<----  Using a Maximum Of 50 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 must
#    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://chris.beams.io/posts/git-commit/
# --------------------

貢献する者の受け入れ基準

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

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

To-Doの定義

GitLabに貢献する場合、変更には単なるコード以上のものが含まれることを知っておいてください。 私たちは、次のような完了の定義を使っています。 これらの要件をすべて満たすことを確認するまでは、あなたの貢献は完了したことにはなりません。

  1. 貢献することの妥当性を説明する明確な記述。
  2. 必要に応じてコメントされた、動作するきれいなコード。
  3. ユニットテスト、インテグレーションテスト、システムテスト。
  4. リグレッションやバグは、そのイシューが再び発生するリスクを減らすためのテストでカバーされます。
  5. パフォーマンスのガイドラインは遵守しています。
  6. セキュリティ・コーディング・ガイドラインに準拠しています。
  7. /doc ディレクトリに文書化されています。
  8. 必要に応じてChangelogエントリを追加しました。
  9. 関連する（UX/FE/BE/テクニカルライティング）レビュアーによるレビューを受け、すべての懸念事項に対処。
  10. プロジェクトメンテナーによってマージされました。
  11. 貢献者がデフォルト設定を変更したり、新しい設定を導入したりする場合は、インフラストラクチャーの課題トラッカーにイシューを作成し、インフラストラクチャー部門に報告してください。
  12. 貢献がデプロイされると、CanaryステージまたはGitLab.comで動作することを確認。
  13. 関連性があれば、リリース記事に追記。
  14. 該当する場合はウェブサイトに追加。
  15. 必要に応じてブラックボックステスト/エンドツーエンドテストを追加します。 ご質問は品質チームまでお問い合わせください。

依存関係

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

  1. リリースのブログ記事に追加されたことに注意してください（まだ存在しない場合は作成してください）。
  2. アップグレードガイド
  3. GitLab インストールガイド.
  4. GitLab開発キット。
  5. CI環境の準備。
  6. オムニバスのパッケージ制作者。

インクリメンタルな改善

私たちは、（イシューの有無にかかわらず）小さな問題を修正するためのエンジニアリングの時間を認めています：

  1. 未優先のバグ修正（プロジェクト移動のバナー警告があちこちに表示されるなど
  2. ドキュメントの改善
  3. Rubocop または Code Quality の改善

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