運用してわかった、GitHubのIssueとDiscussionを個人利用でのベストプラクティス・バッドノウハウ

## 本稿における留意事項
:::note warn
- 個人の主観かつ個人利用での「IssuesとDiscussionsの使い分け」の話であり、目的によってベストプラクティスは異なる
- 開発目的ではないが、部分的に開発プロジェクトでも通じる
:::

:::note alert
- GitHubで完結したいので、GitHub以外のツールやサービスは使わない
- 個人運用以外なら本稿を参考にしてはならない
:::

## 目的・ゴール
GitHubのサービスにちょっと詳しくなろう

## モチベーション
- GitHubのコントリビューションを高めてコントリビューションをスコア化している外部サービス連携

## 比較
運用面やGitHubの仕様から分析する。
参考にProjectsやWikiも入れてある（Wikiについてはプライベートリポジトリは有料）
なお、PRは目的が異なるので項目としては入れていないが、本稿においてはIssuesと同じカテゴリとする。

:::note warn
用途が限定的な中での評価であるため、うまく活用すればもっと高い評価になる可能性はありうる
:::

| 比較項目（ユースケース例） | Issues | Discussions | Projects | Wiki | 評価・備考・補足・コメント |
| ------- | ------ | ---------- | --------- | ---- | ---------------- |
| 脳内ブレインストーミング | △ | ◎ | × | △ | １つのテーマに対して様々な議題があり、意見交換をするというシチュエーションに対応できるのがDiscussionsのみ。Issueはツリー形式ではないので報告のみが良さそう。Wikiは決まったことを書く場所として運用すべきだろう。そうでなければWIPを忘れずに |
| 設計 | ⚪︎ | ⚪︎ | × | △ | 利用シーンが難しい。かなり粒度の高いタスクIssueなら議論が発散することはないが、あれもこれも詰め込んでしまった場合が悲惨[^粒度の高いIssue]<br>IssueにはDiscussionにはない便利な仕組みがあるので日常的に発生しがち[^Issue作成時の便利なCI] |
| 実装 | △[^PR実装] | ⚪︎ | △ | - | タスクIssueの粒度を高めても、必ず１つ以下の議題しかうまれないということはないため、Issueを使って実装を管理する方法は非推奨とした。Issueで議論したい場合、早々にDiscussionsを作ってリンクを貼り付けた方がいいかもしれない。Issue化するほどではない（管理の必要がない）タスクはIssueとは別にProjectsだけで起票を完結できるので案外悪くないとした |
| 一覧性 | ⚪︎ | △ | ◎ | ⚪︎ | Issueが25件以下になるようにすればある程度解決できるが、大規模になるとProjectを推奨。複数の目標やプロジェクトを１つのリポジトリで扱う運用は微妙な気もするが、１つのプロジェクトを複数のリポジトリで横断することはよくある。こういった時はタイムラインや看板が重宝する |
| スケジューリング | × | - | △ | - | GitHubはスケジュール管理をしようとするとUXの観点からは微妙すぎる。まずIssueでマイルストーンを作る場合、マイルストーン自体の管理コストが生じる。Projectsを活用するならマイルストーンは必須だが、（運用はともかく）マイルストーンを起きまくると煩雑化する。Issueテンプレートを使って納期など一覧したい情報をIssueタイトルに入れる運用もあったが、タイトルが圧迫されて視認性が悪くなる |
| 検索（ナレッジ管理） | △ | × | △ | △ | ページ内検索でタイトルを探すのが一番である、という前提が付きまとう。そのためGitHubはWikiであったとしてもナレッジベースとして採用すべきではないし、運用もすべきではない。できなくはない程度。ただしPRに開発の経緯だけでなく運用の仕方（テストだと特に）を書いているケースが非常に多いので外部ツールを活用してでも吸い上げる仕組みは作った方がいい |
| 検索（保守・改修） | ⚪︎ | △ | × | ⚪︎ | いったん検索性は考慮対象外にするが、その上で「どこでやってもメリット・デメリットがある」ため、目的に応じて使い分けるべし。共通する課題として「改修の場合、いずれもリリースバージョンは言及の必要がある」ため、起票時にはPRのIDを含めると良い。`- #PRのID`とすると見やすいのでおすすめ |
| GitHubコントリビューション | ⭐️ | - | - | × | なぜGitHubでやっているか？というと「就活・転職においてGitHubのコントリビューションを評価される傾向があるため」だ。すべての行動はコントリビューションに反映される必要があるのだが、Issue以外対応していないので、もしDiscussionコメントやProjectsを使わないでIssueだけで管理したい場合は、そもそもDiscussionsリポジトリやProjectsリポジトリを作ってしまえば良い。なお、Wikiはよく見れば実態は.gitなので、CIを使ってコントリビューション化できる（ただし要force push） |
|  |  |  |  |  |
|  |  |  |  |  |

[^粒度の高いIssue]: 【設計運用案】Issueにはキャプチャのように子タスクを一覧＋作成できる仕組みがあり、これが目的でIssueを作る事がある。そのため、粒度の高いIssueとそれらをまとめる（作成するためだけの粒度の低い）Issueが共存することになる。要運用対処
[^Issue作成時の便利なCI]: 【粒度の低いIssueから粒度の高いIssueを作るのが捗る仕組み】後日記事にする。
[^PR実装]: PRに限り◎

その他、気付いたら追記しているかもしれない。

#### 凡例
| 記号 | 解説 |
| --- | --- |
| ◎ | 他のツールと比較しても良さそう |
| ⚪︎ | 運用や仕様に気をつければ使える |
| △ | 頑張ればできるがおすすめしない |
| × | △というのもつらいものばかり |
| - | その使い方は想定されていない |

## 一部例
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/122800/f5cb7ca7-1b6b-a707-d477-db8258c24615.png)

ディスカッションをセッション・カテゴリーにスレッドを立てて運用している例。
Qiitaアドカレもかなり計画的に進めている。QiitaTシャツがほしい！というモチベーションしかない。

なお、2024アドカレが始まったばかりではあるが、2025年のエンジニアフェスタに向けて準備をしていることをチラ見せしておく。
（今年のエンジニアフェスタの予定がないのは、知ったのが直前過ぎて何も用意できていなかったことから）

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/122800/6a3305f1-d7c1-5848-4d3a-e80092e4d1a1.png)

日報をIssueで書く形式にした。
日々の業務もあるが、Qiitaアドカレの投稿管理も必須課題であるため、テンプレートを用意しておく
`- [ ] `のように書くとチェック項目になるので、タスク(Fix)リストを書きやすいようにあらかじめテンプレート内にも埋め込んである。

## 所感
GitHubも様々なツールが出てきて使いやすくはなったが、運用ありきな側面を強く感じるので個人でサクッと使うにしても、それなりの規模になったら外部ツールを検討した方が良い。
その上でGitHubにこだわりたい（特にエンジニアであれば）

ただし、コントリビューションに囚われすぎると適正な評価を得られなくなるため、やりすぎはほどほどに。
個人的には1コントリビューションを毎日つけて、とりあえず白抜きを防ぎたいという気持ちはわかるし、そういった仕組みを使っているということ自体がCIスキルが０ではないことの証明になるので他アカウントとの差別化になるという意味でも悪くはないと思っている。
やること自体は悪くないのだが、やりすぎるのは良くないと言及しておく。

### 本日のつぶやき・ポスト・Tweet
アイリッシュ・ケルティックBGMとStable diffusionの解説でよく出てくるアニメ調の女の子モデルイラストの親和性高くない？
本稿の大部分は11月時点で作成したものだが、静かな環境で落ち着いて集中したい時にゲームサントラを聴かない（懐かしいものや最近のタイトルなど不問）傾向があるな、と感じた。

## 結論
控えめに言っても、GitHubのサービス __「だけで」__ プロジェクト管理をするのはおすすめしない。

が、気軽に見える化させるなら十分に使える。
「使いやすさ」は疑問だが「使える」かどうかでいうと十分可能だ。
私などはプロジェクト管理（特にナレッジ）の手法にクセが強い自覚があり、何とか試行錯誤を重ねてＵＸを改善できるよう気にしているのだが、昨今は「私の手法が広まればみんな慣れてきて、結果的に頑張らなくてよいのでは？」という良くない方向にシフトさせつつある。…ような気がしている。

今回のように、なんでもGitHubに解決させるモチベーションはあくまでコントリビューションに反映させたいので、Issue連携は強い方がいいよね！っていうぐらいでしかなかったのだが、結果的にあまり普及させる意味のないものの個人として活動アピールがしやすい手段を一つ発明した、という結果になったのではないかと思う。

とはいえ、本稿の目的は「GitHubのサービスにちょっと詳しくなろう」というもので、それ以上は想定していない。
本稿をきっかけにご自身でもGitHubのサービスを使い倒してみた所感が出てくればぜひ意見交換したいものだ。

### 注釈＋注釈の補足資料
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/122800/508a3196-ca63-8917-3cf8-7afe21951940.png)

内容は作成当時のもの
最新版は直接カレンダーを参照されたい

https://qiita.com/advent-calendar/2024/nomuraya_oreno