Closed2024/12/04にクローズ4

OSS における GitHub Issue と Discussion の使い分け

issue と discussion の機能的な違い
- API
- discussion
  - up / down
  - answer
  - category
  - reply
- issue
  - project で管理できる
  - 同じリポジトリのコードのリンクが展開される
  - GitHub Releases のリリースページで #<issue number> がリンクになる
  - 他の issue や pr から参照したときに timeline 上に表示される
  - title を編集したり label をセットしたりしたときに変更履歴が timeline に出る
  - user を assign できる
  - milestone に追加できる
どちらかだけ使うメリット
- 分散しないで済む
- 使い分けについて迷わずに済む
使い分け
- actionable なものだけ issue にし、それ以外は discussion にするというアプローチ
- discussion は使わない
  - 無効化
  - 半無効化 (既存の discussion を参照できるようにするため、機能としては有効のまま)
- user に issue を作らせない
- 特別な設定なし
  - メンテナが判断して issue と discussion を変換

前提としてここではめちゃくちゃ人気の OSS は考えず star 数 1,000 程度の個人 OSS を考えます。

issue や pr がめちゃくちゃ作られるわけではないが、定期的に作られる感じです。
この場合、正直 Issue だけのほうが良い気はしています。

単純に issue と discussion の機能を比較すると、 issue のほうが現状優れていると思います。

もちろん discussion にしかない機能もあるので一概に優れているとは言えませんが、それらの機能はあまり重要ではないし、むしろ機能がある分どうそれを使うか考えないといけず面倒でさえあります。

特に issue や discussion はユーザーが自由に作ってメンテナではコントロールできない部分もあるので尚更です。
issue と discussion を両方使うと
情報が分散する
使い分けについて迷う
この issue は discussion に変換するか否か、みたいなので迷う
ユーザーとしてもどっちに作るべきか迷う

template の管理の手間も増える
discussion が project で管理できず不便
しかし、一度 discussion を使いだしたあとに無効化すると、過去の discussion を参照できなくなるという問題があります。

以下のような対応方法が考えられます。
discussion を issue に変換する: これはコメントを参照できなくなるはずなので NG
discussion template で warning を出しつつ実質作れないようにする
専用の repository を作って transfer して無効化する: 未検証
issue だけにすると品質的に微妙だったり actionable でない issue が作られて大事な issue が埋もれるという懸念がありますが、それは project で priority のような field を作って priority の高いものからハンドリングするするようにすればあまり問題にならない気はします。
issue の品質が微妙で書き直したい場合、新たに issue 書いて元のを close すればよいでしょう。

これは discussion で議論したあとに issue を作成するのと変わりありません。

Shunsuke Suzuki

残念ながら discussion を transfer する API は v3, v4 ともになさそうです。
手で transfer するとなるとけっこう大変です。

Shunsuke Suzuki

自分の OSS で Discussion をやめる際のアナウンスとかを考えます。

 利用停止の流れIssues Template の追加
Discussion Templates の修正
https://github.com/suzuki-shunsuke/test-github-action-2/blob/main/.github/DISCUSSION_TEMPLATE/deprecated-q-a.yml#L5
https://github.com/suzuki-shunsuke/test-github-action-2/discussions/categories

利用停止の Announce のための Discussion を作成
Document の修正
SNS で共有
--
まだ Discussions を使ってない、または若干使われているけど既存の Discussion が参照できなくなっても良い場合
単純に Disucssions を無効化します。
Discussions が既に使われていて、既存の Discussion が参照できなくなると困る場合
使われていない Category は削除します。

使われている Category の 名前と description, template を修正します。
名前を Deprecate (*) , description を Please use Issue instead にします
https://github.com/suzuki-shunsuke/test-github-action-2/discussions/categories

template の YAML  を更新します
ファイル名を deprecated-*.yml にします
https://github.com/suzuki-shunsuke/test-github-action-2/blob/main/.github/DISCUSSION_TEMPLATE/deprecated-q-a.yml?plain=1

title: Deprecated (Q&A)
body:
  - type: markdown
    attributes:
      value: |
        ## :warning: Please use the issue template instead

        We don't accept new discussions anymore.
        We keep this discussion category only for existing discussions.

        [Please create an issue using the issue template](https://github.com/aquaproj/aqua/issues/new?assignees=&labels=bug&projects=&template=bug-report.yml).
  - type: checkboxes
    attributes:
      label: .
      options:
        - label: ..

 GitHub Discussions の利用を停止します本プロジェクトで GitHub Discussions (以下 Discussions) の利用を停止します。

今後は GitHub Issues (以下 Issues) を利用してください。
過去の Discussions を参照できるようにするため、 Discussions の機能は無効化せずに残しておきますが、 Discussion のテンプレートなどを見てもらえれば分かる通り、新規の Discussion の作成は受け付けておりません。

作っても close します。
Discussions の利用停止に伴い、 Issues Templates を追加しました。

 なぜ Discussions の利用を停止するのか本プロジェクトにおけるタスクの管理をシンプルかつ効率的にするためです。
自分の OSS のタスクを一つの GitHub Projects (以下 Project) で一元管理するため
情報を Issues に集約するため
選択肢を減らし余計な迷いを生まないため
Discussions は Issues と比べて機能が足りてないため
自分の OSS の issue や pull request は全て一つの GitHub Projects (以下 Project) で一元管理されていて、これにより自分は多くの OSS の ticket を適切に管理できています。

しかし、 Discussion は Project で管理することが出来ません。
また Issues と Discussions を両方使うと情報が分散しユーザーとメンテナ双方に混乱を生みます。

ユーザーからするとこれは Issues と Discussions のどちらに作ればよいのか迷いますし、

メンテナからするとこの Issue は Discussion にすべきだろうかと迷います。
Discussions には reply や answer など Issues にはない機能もあります。

これらは便利な側面もありますが、一方でどう使うかで混乱を生みます。

answer した Discussion は close すべきなのか否か迷うこともあります。

こちらとしては reply してもらうことを期待しているのに comment がされてしまってストレスを感じることもあります。
Discussions は Issues と比べて機能的に足りてない部分も多くあります。
project で管理できない
同じリポジトリのコードのリンクが展開されない
GitHub Releases のリリースページで #<discussion number> がリンクにならない
他の issue や pr から参照したときに timeline 上に表示されない
title を編集したり label をセットしたりしたときに変更履歴が timeline に出ない
user を assign できない
milestone に追加できない
これらの問題の一部は Discussions で議論したあとに Issue を作成するようにすれば解消できますが、

毎回 Issue を作成するのが手間であるのと、 Issue にするまでは Project で管理できず、 Project を使ったタスク管理が上手く機能している今、これは望ましい状況ではありません。

 それ以外に検討した選択肢Discussions をやめる代わりに検討した選択肢です。
両方使ったうえで、明らかな bug やアクション可能なタスクだけ Issues にし、それ以外を Discussions にします。

Issues の作成については以下のような 2 つのアプローチがあります。
ユーザーにも Issues の作成を許可しつつ自分の方で必要に応じて Discussions と Issues を変換する
ユーザーに Issue を作らせないようにし、自分が必要に応じて Discussion から Issue を作成するようにする

 Q. Discussions と Issues は用途が異なるものであり、両方使うべきではないですか？こういった意見があるのは理解しています。

実際、以前自分が aqua という OSS の Discussions を廃止したときにも反対意見がつき、結果として復活させたという経緯もあります。

当時も廃止したいという気持ちがありましたが、反対する意見も理解できたので復活させました。

しかし、これらの使い分けはやはり曖昧であり、自分の OSS のタスク管理においてはメリットよりデメリットが勝ると感じています。

 Q. Discussions を Project で管理したいというのが間違っているのではないですか？明らかな bug やアクション可能なタスクだけ Issues にし、それ以外を Discussions にすれば、重要なものは Project で管理され、 Discussions にあるのはそれ以外のものだけになるという考え方もあるかもしれません。

ただ、 Discussions の中には active に議論すべきものが残っていることもあるので、やはりきちんとタスクとして管理したいと思っています。

そうでないと、返事や検討を忘れて放置してしまうでしょう。

 Q. 全部 Issues にしたら重要な Issues が埋もれるのではないですか？自分は全ての Issues と Pull Requests を一つの Project で一元管理していて、それらの item に priority を設定しています。

そのため、 priority の高いものが低いもののせいで埋もれることはありません。

 Q. 今後 Issues や Discussions の機能改善によって方針が変わることはありますか？Discussions と Issues の運用についてはこれまでも試行錯誤を重ね、運用が変わったこともありました。

そのため、もちろん将来的に変わる可能性はあります。

上記で述べた Discussions に足りない機能は、今後実装されて解消されるかもしれません。

しかし、仮に今 Discussions に足りない機能が実装されたとして両方使うかと言われると、使わないのではないかと思います。

両方使うことによる情報の分散や運用負荷の増大は変わらないからです。

Issues に統一してシンプルな運用にするほうがユーザー・メンテナ双方にとって幸せではないかと思います。

このスクラップは2024/12/04にクローズされました