この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。
以前チーム内でタスク管理の精度を上げるためにIssueとPRについてルール付を行い、ガイドラインとしてのテキストも作成しました。
これで迷いはなくなったと思っていましたが、一つ難点が。予めルール付したIssueの定義を埋めることができない、つまりはやるべきことが確定していない「ふわっとした」状態の所謂「提案」や「願望」を置くことができません。
コントリビューター向けテキストに書いた「マイルストーン」での解決も試みましたが、このマイルストーンはIssueとして確定したもののみを含めることができる仕様でした。要は私の動作把握漏れ。代わりの手段は無いものかとGitHubリポジトリの各機能を触っていたところ、Projectがそれに該当していました。
Projectの動作を理解している方は多いはずですが、Issue・マイルストーンとの組み合わせで使う場合の具体的なワークフローについては明記されている例を見かけず、割と曖昧です。実際のProject動作を見て、落とし所を検証してみました。
Projectの使い方
所謂オンラインでのカンバンです。Trello等を使ったことがある場合はお馴染みかもしれませんが、GitHubの場合は用途に応じてテンプレートが用意されています。
- None
- Basic Kanban
- Automated Kanban
- Automated Kanban with reviews
- Bug triage
基本は状況に応じてカードをカラム間移動させることに変わり有りませんが、テンプレートによってはIssueやPRのステータスに応じて自動でカラム間の移動が行われます。
None
初期設定では一つもカラムがありません。カラム種類に応じた他のテンプレートにあるIssueやPRとのhook機能は存在しており、カラムやhookを手動追加することで他のテンプレートと同一の構成を作ることもできます。
Basic Kanban
以下3つのカラムで成り立つカンバンです。
- ToDo
- InProgress
- Done
ポイントはIssueやPRとのhookが有効になっていないところです。作成したIssueやPRを管理することもできますが、進捗があってもカンバン上でのステータスには反映されません。故にIssueやPR等、GitHub特有の機能を伴わない、ベーシックな使い方で問題ない場合にはおすすめです。
Automated Kanban
見た目にはBasic Kanbanと変わりません。大きな違いとして、IssueやPRをProjectに紐付ると該当カンバン上に表示されるようになります。
実際に使ってみると期待する動作と以下2点で異なるかもしれません。
- IssueはTodo扱いになり、完了するとDoneに移行する
- PRはInProgress扱いになり、mergeされるとDoneに移行する
TodoからInProgressに、最後Doneへ、とはいかないのが特徴です。Issueを単純なTodoリストとして、ソースコードへのアクションをInProgressと見た場合にはマッチするかと思われます。
PRをmergeした際にIssueをクローズする仕組み(fix #XXX)にしておくと纏めてDone送りになり、手間が省けます。
Automated Kanban with reviews
Automated Kanbanと異なる点として以下の2点があります。
- review中のPR用カラムReview in progressが追加され、approve数を得るとReviewer approvedに移行する
- mergeに必要なapprove数を得たPR用カラムReviewer approvedが追加され、mergeされるとDoneに移行する
複数人のチームでreviewを機能させている場合に用いるテンプレートというわけです。
Bug Triage
バグフィックスを管理したいときに使えるテンプレートです。ポイントはGitHub上では「Bug」という区分がないところ。
Issueをhookさせておき、カンバン上に現れたIssueをバグフィックスの優先度にて応じて「High priority」か「Low priority」のいずれかに手作業で移行させる程度です。勿論優先度を更に細かくする手段もありです。
実際の運用
IssueとPRのhookを活用する
各テンプレートのhookを活用したい場合の一例として、以下のようなルールが考えられます。
- IssueとPR作成時に忘れずにAutomated Kanban with reviewsのProjectに追加しておく
- カンバン上でIssueとPRのカードを直接操作しない
IssueとPRの一覧ではステータスが俯瞰し難いため、状況をカンバンでフォローする、という構図です。Issueのカードには紐づくPRも表示されているため把握しやすくなります。
Reviewについては、
Review in progressにてレビューが完了していないPRをチェックReviewer approvedでmergeしていないPRを完了する
という手続きにてReview漏れが減らせるかもしれません。
Issueとしては未だ起こせないTodoも管理する
Issueに必要な要件を満たせないものの追加したいパターン。例えば以下。
- 具体的な作業が固まっていないが要望として出ているもの
- 覚書に等しい状態
- 複数の内容が含まれていて整理が必要な案件
使い方の一例として、
- カンバン上でCardとして追加(Issue未満)
- 決まった要件を追加していく
- 必要に応じて分割
- Issue化出来るタイミングでIssueにする
というものが考えられます。
管理すべき範囲が広くみえそうですが、全員での共有時及び作業時に必ず見るべきはIssue Listのみです。上図内のカンバンについて、使い方の例を以下に挙げてみます。
Basic Kanbanの使い方
要望や覚書を詰める時に。個々で作成して下書きのような扱いにしても問題ありません。チーム全体で共有を義務化する必要もありません。使わない選択もありです。相談したいときにCardのLinkを渡して見てもらうとよいでしょう。Issueとまでは行かずになかったことにしたい場合はArchiveとしておきます。
カンバンに直接追加するとCardとして扱われます。Issue前段階であり、実作業は発生していないため進捗には値しません。要件を固めてIssueに変換するとIssue一覧にも追加され、カンバン上では表示がCardからIssueへ変わります。
このカンバンのポイントは、自身のIssueやCardが大量に溜まるところです。不要なCardは適度にArchiveし、大量のIssueに悩まされるようになった場合は今解決すべきIssueであるかを確認すべきです。必要に応じてマイルストーンにてこなす期日を調整しましょう。
Automated Kanban with reviewsの使い方
IssueやPR一覧のサムネイル版としてつかいます。定例等での共有時に報告のベースとして使うのもありですし、IssueとPRの状況を纏めて確認するだけに使うのもありです。IssueやPRの操作と連携しているため、基本追加作業は発生しません。
Basic Kanbanから派生したIssueはAutomated Kanban with reviewsにも存在することになりますが、両方のカンバンでhookは機能するため完了すると同時にDone移行となります。
あとがき
道具は使いようといいますが、GitHubの場合は説明不足感もあり、只管試していい塩梅を追い求めるしかなさそうです。
基本はIssueListにて。期日決めをマイルストーン、メモ書きやIssueとすべきかの判断或いは全体進捗の俯瞰をProjectベースで検討すると、なかなかいい感じに動作するように思えました。
2
