knqyf263's blog

自分のためのメモとして残しておくためのブログ。

OSSで新機能要望やバグ報告を全てGitHub Discussionsに起票してもらうことにしてみた

今回の案は自分のメンテナンスしているOSSだと回りそうという話で、これが他のプロジェクトにとっても良いと勧めているわけではないです。 ふーんそういう運用をしているところもあるんだと思って読んでもらえればと思います。

要約

バグ報告や新機能追加の要望などをGitHub IssuesではなくGitHub Discussionsに起票してもらうことにしました。 作られたdiscussionのうち、以下のものはissueを作ります。

  • 受け入れることに決めた新機能、かつ実装方針が明らかなもの
  • バグであることが確認できたもの

こうすることの利点として、GitHub Issuesには実行可能なタスクのみが残ることになります。TODOリストのようなものです。議論はGitHub Discussionsで行い、タスクはGitHub Issuesで管理します。

実際GitHubのドキュメントにも以下のように書いてあります。

GitHub Discussions を使用して、全体像のアイデアについて話し合い、ブレインストーミングを行って、プロジェクトを Issue にコミットする前にプロジェクトの特定の細部を詰めて、スコープを設定できます

ただ全てのチケットを一旦Discussionsに集めるというのはやや過激なやり方です。 これは複雑な運用にしたくないという思いや我々のOSS固有の事情もあるので、その辺の理由も今回書きました。

まだ始めて1週間程度なのでやっぱりうまくいかないわ、となるかもしれないですがここに至るまでチームでも色々議論していたので現時点での考えを整理しておきます。

背景

自分は仕事でOSSをメンテナンスしているのですが、GitHub Issues（以下、Issues）への報告が毎日そこそこの数来ます。巨大OSSになると未完了のissueが数万件とかあるのでそれに比べれば全然少ないとは思うのですが、それでも少人数で捌くには十分多くいくつかの問題を抱えていました。

質問への回答

単に「これどうやって設定したらいいの？」みたいな質問もIssuesに来ていました。Issueテンプレートを使ってラベルを付けることで区別していましたが、やはりIssuesが混沌としていく感じはありました。

バグ報告のノイズ

作っているOSSの性質上バグ報告にノイズが多いなと感じています。これについては以前ブログを書きました。

knqyf263.hatenablog.com

詳細は上の記事を見てほしいのですが、バグとして報告されても報告者の勘違いなことが多いです。セキュリティツールの性質上仕方なくはあるのですが、本当に直すべきバグ報告と実際には存在しないバグ報告がIssuesに混在していました。ラベルで頑張っていましたがやはり大変なのでどうにかしたいなと思っていました。

バグと言われることの精神的苦痛

上の件と似ていますが、自分が勘違いしているとは思わずにツール側が間違っていると思いこんでしまう人が少なくありません。 「ドキュメント見落としているかも」とか「設定間違っているかも」と思って質問として起票してくれる分には良いのですが、「絶対お前らが間違っている！バグに違いない！！B・U・G！！B・U・G！！」みたいな人も多いです。 本当にバグな場合は全然良いのですが、勘違いでバグだ！！と断言され続けるとしんどくなってきます。

Tweetの反応を見ていたらバグと言われ続けるの確かにしんどいという反応がいくつかあって、OSSあるあるのようでした。

自分個人は「OSSなんだから自分で直してくれ！」という考えが身に染み付いているのでスルーしたりもしていますが、チーム全体で言うとやはり仕組みでなんとかしたいなという気持ちがありました。

ちなみに断っておきますが、バグ報告をしないで欲しいという意味では全く無いです。 むしろ気軽にissueを立ててくれると助かると考えています。 そしてバグかどうかに関してもメンテナのほうが当然実装に詳しいのでユーザ側に誤解があるのも仕方ありません。 なのでこれはユーザへのお願いというよりは、そういう前提のもとで何とかする方法を考えなければならないという話になります。 もちろんユーザ側でも「これって本当にバグなのかな...？」と一度立ち止まって考えてもらえると嬉しい気持ちはありますが、今回はその話は置いておきます。

新機能要望

新機能要望はしばらく見ていると実現不可能な永遠にクローズできないものがIssuesに溜まっていくことに気づきました。 どうやって実装したらよいか皆目見当がつかない、でもアイディアとしては面白いしいつか何か新しい技術が現れたり実装方法を思いついたらやりたい、というものは結構多くあると思います。 こういう場合にクローズするわけにもいかないし、ただ放置されるということが多かったです。

Issuesの横の数字が増えていくことへの嫌悪感

少し話がそれますが、自分はメールの受信ボックスは常に0件にしておきたい派です。 メールアプリの右上に数字が出るのが嫌いです。 メール＝タスクのように捉えているので、タスクが溜まっているのを常に突きつけられるのがしんどいのだと思います。 これは個人差があると思います。アプリの右上の数字が凄いことになっている人も少なくないと思います。

自分の場合、GitHub Issuesも同様に感じていました。 定期的にそんな感じのことを言っています。

もちろん本当にタスクなら良いのですが、そうではないカスタマーサポート的なチケットが溜まっていくのは複雑な思いでした。

Issues対応への強迫観念

Issuesはやはりタスクとしての意味合いが大きいので、大量のバグ報告が来るとたとえ勘違いであっても「直さなくては...」となって精神的にすり減ってしまうということもありました。 あとは質問の場合は必ずしもメンテナーが答える必要はなく利用者同士で助け合っても良いはずですが、Issuesだとどうしてもそういう雰囲気が醸成しにくかったように感じます。

マイルストーン決めるときにタスクの選定が面倒

マイルストーンを作成するときに新機能要望一覧からどれやろうかなーと考えたりするのですが、これもIssuesに全てごちゃ混ぜになっているせいでやりにくかったです。 もちろんこれもラベル運用はしていたものの、ラベル付け忘れて埋もれるやつとかもありましたし、そもそもフィルタリングのために追加でワンアクション必要というのは意外と煩わしさを感じました。

運用案

他にも挙げると色々あるのですが、とりあえずIssues単体での運用が難しくなっていました。 そこでGitHub Discussions（以下、Discussions）をより活用しようとなりました。 以前のDiscussionsは回答をマークすることができるだけでQ&Aな使い方がメインでしたが、最近クローズ機能も追加されもう少し幅広い活用が出来るのでは？となり運用方法を模索し始めました。

github.blog

そこで、以下のように役割を明確に分けることにしました。

  • GitHub Issues
    • 実行可能なタスク
      • 追加したい新機能
      • 修正が必要なバグ
  • GitHub Discussions:
    • 議論が必要なものや明確なゴールを持たないもの
      • 新機能のアイディア
      • バグと思わしきもの（誤検知等含む）
      • 質問

理想的には「実行可能なものだけGitHub Issuesにしてください」とユーザにお願いすることですが、バグなどはユーザ側の判断は難しいです。 新機能については追加したいかどうかはメンテナにしか決められません。

そのため、我々の運用としては”一旦全てDiscussionsに起票してもらう”になりました。 UI上からはdiscussionしか作成できない設定もしています（URL直接踏めばissueも作れますが）。 その後、議論や調査を経てIssuesに起票し直します。 具体的には以下の条件を満たした場合です。

  • 受け入れることに決めた新機能
  • バグであることが確認できたもの

イメージとしては"ユーザからの起票は全て質問として扱う"です。 Discussionsはカテゴリを作成できるので、以下のようにIdeas/Bugs/Q&Aなどを用意していますが、メンテナは全てがQ&Aと思っておきます。

そして得た質問を適切に新機能要望やバグ報告などのIssuesにしていきます。 discussionでとっ散らかったあとに合意した結論をまとめるほうが綺麗になると思うので、discussionの内容をもとに端的にまとめ直してissueを作るという運用にしています。 例えばバグ報告に関しては以下のようになるのが理想です。

  • GitHub Discussions
    • どのように想定と異なる挙動が起きているかを説明する
    • e.g. このオプションを渡すとクラッシュする
  • GitHub Issues
    • なぜそのバグが起きているのかを説明する
    • e.g. このオプション渡すとこの値がnullになってしまいクラッシュする

ただし上のDiscussions/Issuesの分類条件に従うと、バグは再現できたけど原因が分からないものもあると思います。 その辺はあまり厳密にせず、今のところは再現できてバグだと認めた場合は全部Issuesにしています。

この運用には以下のような利点と懸念があると考えています。

利点

タスクの分離

新機能について実現可能かつ実装したいものだけをIssuesに置くことでタスクが区別できるようになりました。 一方、以下のような新機能要望はDiscussionsに置いておきます。

  • 実現可能だが本当に追加するべきかは議論が必要のようなもの
  • 実現不可能なもの
  • 意図が不明なもの

バグ報告についてもIssuesには再現可能かつ修正すべきものだけを置くことでタスクが明確になります。 以下のようなバグ報告はDiscussionsに置いておきます。

  • まだトリアージできていないもの
  • 再現ができないもの
  • 意図が不明なもの

質問に関してはタスクではないのでそのままDiscussionsに置いておきます。

コミュニティ内のコミュニケーション促進

Issuesはメンテナとの対話感が強めでしたが、DiscussionsはStack Overflowのような中立感があるのでコミュニティの人々も気軽に書き込めることを期待しています。 これはGitHubもそのように意図して作っていると思うのですが（多分）、GitHubユーザに浸透するのはまだ時間がかかるかもしれません。

メンテナの精神的負担軽減

一方でメンテナ側はDiscussionsはよりコミュニティ向けの運用をすると決めてしまえば楽です。 Discussionsに来たバグ報告も「誰か再現してみてくれ〜」のように言ってしまって良いわけです。 これはIssuesでも出来る運用ではあるのですが、上に書いたようにIssuesはタスク感強めなので「早くクローズしたい」となって少しプレッシャーがあります。 "Discussions"という名前的にも「議論だしな！」と思って気持ちが楽になります（個人差あり）。 気の持ちようではあるのですが、チーム内で明確にIssuesとDiscussionsでスタンスを区別することでやりやすくなることを期待しています。

現実から目を背けるというか臭いものに蓋をするような感じもありますが、OSSでお金もらっているわけでもないですしメンテナが気持ちよく運用できればヨシ！

懸念

一方で懸念もあります。

アサインができない

Discussionsは議論の場なのでアサインがないのは納得なのですが、このバグの再現できるかやってみてくれない？とチームメンバーに振りたいこともあります。 そういうときにアサインがないと自分に振られたdiscussionの一覧が表示できないので少し不便です。

参照しているIssuesが表示できない

GitHubではとあるissueから他のissueを参照している場合に参照されている側のissueからも参照元が見えます。 Discussionsでは現在それができないようで、そのdiscussionを参照しているIssuesやDiscussionsの一覧が取得できないのは結構不便です。 これはGitHubが今後追加していってくれることに期待です。

なお、discussionをもとに作ったissueは表示されます。

トリアージが終わっていないバグはissueにならない

上で説明したようにバグと確信するまでは一旦Discussionsに置いておく運用なので、単に時間がなくてトリアージ出来ていないものがDiscussionsに残り続けることがありえます。 これはタスクが分離できていなくて良くない状態ですが、全てのバグをトリアージしようとすると永遠に機能開発ができないのである程度割り切っています。 より複数のユーザが同じバグ報告をしてきたら優先度を挙げてトリアージする運用で何とかやっていこうと考えています。

再現ができないバグはissueにならない

上記同様、特定の環境でのみ再現するバグなどが手元でうまく再現できずにDiscussionsに残り続けることがあります。 これはコミュニティに助けを求めて早めにトリアージできたら良いなと考えていますが、こちらもある程度割り切りです。

ユーザがバグ起票後にすぐPRを作ることができない

上の"トリアージが終わっていないバグはissueにならない"と本質的には同じ問題なのですが、小さいバグの場合はユーザが起票してすぐにPRを作ってくれることがあります。 ただし今のフローの場合はdiscussionを作ってからissueを作成するようになっているため、discussionに対してPRを作ることになってしまいます。 これは懸念というより実際に運用してみて既に起こっている問題なのですが、その場合はメンテナ側でPRレビュー時にissueを作ることで対応しています。 少し手間な感じはありますが、利点のほうが多いので現状は運用でカバーしています。

実現方法が思いつかないだけで追加したい新機能がissueにならない

メンテナが良い実装方法を思いつかないけどユーザが思いついていきなり凄いPRを送ってくることがあります。 こういう場合、そのアイディアはDiscussionsに残ったままになっているのでユーザが「メンテナはこの機能追加したくないのか...」となってPRを送るのをやめてしまうかもしれません。 こういうアイディアについては「良い実装方法が思いつかない」となるべくコメントを残して受け入れたくないわけではないことを明示することで理解してもらえることを期待しています。

ただ実装方針が明らかでないものは議論が必要だと思うので、凄い案を思いついたユーザもPR送る前に軽くdiscussion上で議論してもらえる方が健全な気がするので、この運用でそこまで悪くはないかと考えています。

いちいちdiscussion作るのが面倒

ここまでの運用方法はよりユーザ向けであって、メンテナは直接issueを作っても良いと考えています。 "New issue"ボタンからはissue作成はできなくなっていますが、issue作成用のURLをブックマークでもしておけば問題なく作れます。

代案

いくつかチーム内で出た議論についても残しておきます。

バグ報告を廃止して全て質問にしてもらえば？

数年OSSを運用して得た知見としては質問などはせずに「バグだ！！」と言いたい人が一定数存在します。 なのでバグ報告の窓口は残しておいてバグと言いたい欲求を満たしてもらいつつ、メンテナ的にはバグ報告はDiscussionsに置いて質問として扱います。

議論が必要なIssuesだけDiscussionsに変換したら良いのでは？

実際しばらくこれで運用していたのですが、トリアージする時間が取れない間どんどんIssuesが溜まっていって精神衛生上良くないので逆にしました。

Q&Aでユーザが"Mark as answer"してくれない場合はどうすれば良い？

Discussionsでは返答を"answer"としてマークすることができます。 これは主にQ&Aで使われるべき機能で、質問した人がマークしてくれるのが理想です。 ですがマークしてくれない人も多くQ&Aに回答済みにも関わらずクローズされないdiscussionが溜まっていきます。 これについてはメンテナ側がマークしちゃって良いのではないかと思っています。 もし疑問が解決していなければまたコメントしてくれるでしょうし、その場合は"Unmark as answer"も可能です。

新機能は直接Issuesでも良いのでは？

これは結構悩んだのですが、あまり複雑なルールにすると結局破綻するので一旦全部Discussionsで！ぐらいの簡単なルールにしました。 整合性を取るため実行可能なもののみIssuesに置くというポリシーを定め、Discussionsとの役割の違いを明確にしました。

まとめ

ノイズの少ないOSSプロジェクトだとこういう運用は不要かもしれません。 また、Issuesが溜まっていっても構わんよという場合も不要だと思います。 個人の性格に依存する話が多いと思うので多くのプロジェクトに当てはまるかは微妙ですが、OSSで消耗した人の話は世界的にもよく見かけるので少しでも気楽に運用するための参考になれば幸いです。