自分の OSS のタスク管理方法
本記事では自分がメンテしている OSS のタスク管理方法について紹介します。
自分は aqua や tfcmt, tfaction など様々な OSS を開発しており、日々多くの Issue や Pull Request をハンドリングしています。
これらの OSS に関してやらないといけないことは非常に多く、タスク管理に苦慮していた時期もありました。
しかし最近になってだいぶいい感じに管理できるスタイルが確立出来てきたので紹介したいと思います。
- 全ての Issue や Pull Request を一つの GitHub Project で管理
- Project の Item に 数値で Priority を設定し、高いものから処理
- Renovate の Pull Requests は基本自動でマージされるように各リポジトリで CI と Branch Rule Set を設定
- GitHub Discussions の使用をやめ、 Issues に一本化
1. 全ての Issue や Pull Request を一つの GitHub Project で管理
これは以前ブログで紹介したやつです。
自分のリポジトリで作られた Issues や Pull Requests が全て自動で 1 つの GitHub Project に追加されます。
以前はこの Project の整理までは出来ておらず、ごちゃごちゃしていて上手く Project を活用できていませんでした。
今では頑張って整理して結構きれいに使えています。
2. Project の Item に 数値で Priority を設定し、高いものから処理
Project には幾つか View がありますが、主に使っているのは 1 つだけです。
この View には全てのリポジトリの Open な Issues と Pull Requests が集約されています。
各 Item には Priority という数値型の Field があり、 Priority によってグルーピング・ソートされています。
新たに作られたばかりの Issue など、 Priority が設定されてないものは一番上に表示されます。
まずは Priority が設定されてないものをチェックし Priority を設定します。
直ぐ見るやつは一番高い Priority を設定し、逆に見ないやつは一番低い Priority を設定するか、アーカイブします。
Web UI からアーカイブするのは逐一確認が入って面倒なので雑に Priority を 1 に設定することが多いです。
Priority の数値には特に上限などはありません。
一番 Priority の高い Group の item の数が 10 超えるくらい増えてきたら、その中から優先的に見るやつを幾つか pick up して Priority をインクリメントします。
基本これだけで非常にシンプルな運用に落ち着いています。
item には TODO, DOING, DONE のような status もあり、以前はこれで管理していたこともありましたが、 Priority による管理がうまくいっている今は特に status は使ってません。
3. Renovate の Pull Requests は基本自動でマージされるように各リポジトリで CI と Branch Rule Set を設定
以前ブログで書いた通り、 CI と branch rule set を適切に設定すれば Renovate の PR は基本自動でマージできます。
ただ、自分が管理する全部のリポジトリでこの記事のようにいい感じになっていたかというとそんなことはなく、結果として Renovate の PR が自動でマージされずに溜まってしまっていました。
そこで溜まっているやつを一つ一つチェックして CI と branch rule set を設定しました。
その結果、ほとんどのリポジトリで Renovate の PR が自動でマージされるようになり、 Project に PR が溜まることもなくなりました。
4. GitHub Discussions の使用をやめ、 Issues に一本化
GitHub Discussions の使用をやめ、 Issues に一本化しました。
Discussions が元々使われていないリポジトリでは Discussions を無効化しました。
使われているリポジトリでは Discussions を無効化してしまうと過去の Discussions が見れなくなってしまうため、有効のまま新規の新規の discussion の作成を禁止しました。
新規の作成を禁止するという機能はありませんが以下のような対応を入れました。
- 使われていないカテゴリの削除
- カテゴリの名前を
Deprecated (<元のカテゴリ名>)に変更 - テンプレートを修正し、まともに discussion を作成できないようにする
- ファイル名を deprecated-*.yml にします
- https://github.com/aquaproj/aqua/blob/main/.github/DISCUSSION_TEMPLATE/deprecated-bug-report.yml
- discussion が作成されたら GitHub Actions で自動で close
Discussion を自動で Close, Lock するための action も作りました。
- 共通の Issue と各リポジトリの Issue を作成し、 CONTRIBUTING.md を更新
あとは Discussions Templates を Issue Templates に移植し、今まで Discussions に作ってもらってたようなものも Issues に作成してもらうようにしました。
既存の Discussions を Issues に移行するためのツールも作りました。
lintnet ではこのツールを作って全 discussions を issues に変換して Discussions を無効化しました。
e.g. https://github.com/lintnet/lintnet/issues/701
既存の Discussions はそのまま
今回は新規の discussions の作成を禁止しましたが、既存の Discussions は基本そのままなのでコメントを追加したりすることは可能です。
先述の通り Discussions を Issues に変換するツールも作ったので、変換して Issues に移行してもよいのですが、未定です。
Dicussions の更新はメールが来るようになっているので気付けるようにはなってますが、 Project で管理できないので対応を忘れるかもしれませんが、ご了承ください。
なぜ Discussions の使用をやめたのか
- Discussions は GitHub Projects で管理できないため
- 情報を Issues に集約するため
- 選択肢を減らし余計な迷いを生まないため
- Discussions は Issues と比べて機能が足りてないため
- 運用をシンプルにするため
先述の通り GitHub Projects による Issue や PR の管理はうまくいっています。
しかし、 Discussions は Project で管理することが出来ません。
せっかく Project でいい感じに管理できているのに Discussions があるとそれが不完全になってしまいます。
また Issues と Discussions を両方使うと情報が分散しユーザーとメンテナ双方に混乱を生みます。
Issues と Discussions 両方を検索しないと情報を見落としますし、 Issues と Discussions 両方に同じようなものが作られることもありました。
ユーザーからすると Issues と Discussions のどちらに作ればよいのか迷います。
メンテナからするとこの Issue は Discussion にすべきだろうかと迷います。
Issues と Discussions の使い分けのルールを決めたとしてもユーザーがそれを守ってくれるものではありませんし、ルールが破られれば当然ストレスを感じますし、コミュニケーションが必要になります。
Discussions には reply や answer など Issues にはない機能もあります。
これらは便利な側面もありますが、一方でどう使うかで迷いを生みます。
answer した Discussion は close すべきなのか否か迷うこともあります。
reply してもらうことを期待しているのに comment がされてしまってモヤっとすることもありますし、自分自身今のは reply じゃなくて comment すべきだったなと軽く悔いることもあります。
Issues にはこういった機能がないことで逆に迷ったりせずにシンプルに運用をすることが出来ます。
Issues には Discussions にない機能もあります。
- project で管理できる
- 同じリポジトリのコードのリンクが展開される
- GitHub Releases のリリースページで
#<discussion number>がリンクになる - 他の issue や pr から参照したときに timeline 上に表示される
- title を編集したり label をセットしたりしたときに変更履歴が timeline に出る
- user を assign できる
- milestone に追加できる
Q. Discussions と Issues を上手く使い分けたらどうか？
世の中には Discussions と Issues を上手く使い分けているプロジェクトもあります。
- Ghostty: https://x.com/mitchellh/status/1852039089547309552
- Renovate: https://github.com/renovatebot/renovate?tab=readme-ov-file#issues-and-discussions
以下のような運用が考えられます。
- ユーザーには Issue を作らせない。作られたら自動で Close する。代わりに Discussion を作ってもらう
- Discussions で議論をし、メンテナが必要に応じて Issue を作る
Issue の作成者をメンテナに限定することで、 Issue を本当に必要で、アクションが明確で、必要な情報がしっかりと書かれた品質の高いものに限定することが出来ます。
この運用がうまく行けば理想的かもしれません。
ただし、自分には合わないと思いました。
Discussion