0010-チケット駆動の執筆

• ステータス: 採用
• 提案者: @suin
• 参加者: @suin, @canalun, @jamashita
• 更新日: 2023-02-24

プルリクエストをマージしない場合、プルリクエスト作者の時間と労力が無駄になり、申し訳ないという問題がある。これを解決すべく、プルリクエストを作成する前に、issueで話し合うプロセスを採用します。

背景: コントリビューターの増加

サバイバルTypeScriptのコントリビューターの増加に伴い、プルリクエストが増えてきました。プルリクエストの中には、マージされないものも出てきました。その理由として、本書の方向性と合わないといった理由が多いです。

課題1: 労力などがもったいない

プルリクエストは、コントリビューターの時間・労力・才能が注ぎ込まれて作られます。そうした貢献を取り込まないことは、時間・労力・才能を無駄遣いすることに他なりません。これは、コントリビューターにとって望ましいことではないでしょう。

課題2: 断るのが心理的負担

プルリクエストを断ることは、メンテナーにとっても難しいことです。プルリクエストの背後にある時間や労力について考えると、ひとことでは断れません。読者のことを考えるとマージすべきではないと思いつつも、コントリビューターのことを思うとマージしてあげたい。そんな板挟みもあります。そうした心理的負担は、メンテナーにとっての問題であり、執筆を進める上での抵抗にもなっています。

解決策: チケット駆動

上の課題を解決するのがチケット駆動です。「着手する前に話し合いましょう」というのが趣旨です。

着手する前に話し合うことで、上の課題が解決し、次のメリットがあります。

• 本書の方向性とあったプルリクエストが生まれやすい
• コントリビューターの時間・労力・才能の無駄遣いが減る
• メンテナーの心理的負担が軽減される

また副次的に次のようなメリットもあります。

• 変更の経緯が追える。変更についてどのような議論がなされたのか、なぜ変更する必要があったのかなどを後の人が知れるようになります。

もしもチケット駆動でないプルリクエストが作られた場合

もしも議論をせずにプルリクエストが作られた場合は、次のプロセスを行います。

• issueから始め直す。議論が必要そうであれば、issueからやり直す必要があります。
• そのままマージする。議論が必要なく、取り込む必要性が自明なときはマージする。

ただし、できるだけチケット駆動を崩すべきではないと思うので、issueから始め直すがデフォルトフローとなるようにします。

また、issueなしにプルリクエストが作られた場合は、Closeされるリスクが高いことをドキュメントで注意喚起しておきます。

副解決策: PULL_REQUEST_TEMPLATE.mdの導入

PULL_REQUEST_TEMPLATE.mdを用意しておき、チケット駆動で行っていることを旨をそれに含めておきます。こうすることで、プルリクエストを作成する際にその内容が表示されるため、新規参加者もチケット駆動に気づきやすくなります。この解決策は、課題1には効果が薄いですが、課題2への解決策にはなります。

補助策: GitHub Actionsで「Close {issue_number}」をチェックする

GitHub Actionsでプルリクエストの本文にイシューを閉じる指示「Close {issue_number}」が含まれているかをチェックし、チケット駆動が原則として働く環境づくりをします。

使用するGitHub Action: https://github.com/marketplace/actions/verify-linked-issue

いくらチケット駆動を謳っても、それを働きかける環境がないと形骸化しそうです。形骸化を防ぐためには、このGitHub Actionsが有効そうです。

関連PDR

なし