チケット駆動(プルリクする前に話し合おう)
唐突に送られてくるプルリクエストには、事前に認識合わせができていないため、本書の方針にそぐわないものや求めていないものがあります。そうしたプルリクエストはマージされずにクローズとなることがあります。
プルリクエストを作成するには時間と労力を要しますが、マージされなければその時間と労力が無駄になってしまいます。これは非常にもったいないことです。
このような事態を避けるために、本プロジェクトではチケット駆動が原則とし、「プルリクする前に話し合おう」をモットーとしています。
改善点が見つかったとき、すぐに手を動かしたい気持ちは理解できますが、まずはissueを作成いただき、話し合いのステップを踏んでからプルリクエストに進んでいただくよう、ご協力をお願いいたします。
チケット駆動の流れ
チケット駆動の流れは次のようになります。
- issueを作る
- 話し合う
- 着手する (話し合いが深まるなどして、頃合いを見計らってから)
- プルリクエストを作る
- マージ
issueを作る
本書に変更を加えたいときは、そのアイディアをissueとして共有してください。
issueには次の内容を記してください。
- 何をどうしたいか？
- そうしたい理由は何か？ (誤植の修正など理由が自明な場合は不要)
- やるとなったら自分が担当したいか？ (自分がその変更のプルリクエストを作りたい場合)
誤植の修正など、軽微な変更と思われる場合でも、まずはissueから始めましょう。
話し合う
issueにて、メンテナーを含めて話し合いをします。話し合いでは次について話し合います。
- そもそもやるべきか？
- 他によいアイディアは無いか？
- 誰が担当すべきか？
話し合いが執筆会などの口頭で行われた場合は、その記録をissueに残すようにします。
メンテナーが「やらない」と判断した場合は、issueをクローズします。
着手する
十分に話し合い、メンテナーが「やる」と判断した場合に着手のステップになります。着手する人は、メンテナーが決めます。
プルリクエストを作る
着手した人は、変更をプルリクエストとして作成します。
プルリクエストの作成時にはGitHubのキーワードを用いたissueの関連付け機能を用いて、対応したissueをプルリクエストに関連付けてください。これには2つの目的があります。ひとつは、プルリクエストの経緯をたどれるようにすることです。もうひとつは、プルリクエストがマージされた際に、issueが自動クローズされるようにするためです。たとえば、issue #123を解決するプルリクエストであれば、本文中に次のようなキーワードを書きます。
markdown
markdown
マージ
メンテナーがプルリクエストの内容を確認し、問題なければマージします。
チケット駆動でないプルリクエスト
もしもチケット駆動でないプルリクエストが作られた場合は、次のいずれかのプロセスに従います。
- issueから始め直す。
- 例外として、議論の余地がまったくなく、取り込む必要性が自明な場合は、そのままマージすることがあります。ただし、できるだけチケット駆動を崩さないようにするため、issueから再度はじめることをデフォルトフローとします。
過去には、チケット駆動でないプルリクエストが、事前の認識合わせが十分でなかったため本書の方向性と合わせきれず、クローズとなってしまった例もありますので、できる限りチケット駆動に則ることをお勧めします。