本記事では主にGitHubのIssuesとProjectsの概要、使いどころを取り上げます。
※初心者向けの記事です。
◇補足
- 本記事は2024年時点の内容で書いています。
※GitHubはバージョンアップが早いため、最新情報は変わっている内容が高いです。 - Classic Projectsの内容は含んでいません。
では、以下目次となります。
Issuesについて
リポジトリについてくる機能で超簡易的なチケット管理が出来る仕組みです。
作成した各IssueはCommitと連携させることも可能です。
下記がIssueの作成画面です（シンプルな構成）。
コメントエリア（返信可）がメインとして存在し、他に
- Assignees（担当者）
- Labels（ラベル）
- Projects（プロジェクト）
- Milestone（マイルストーン）
などのフィールドが固定的に存在します。
出来ることの例
概要
Issuesを使うことで、要望や実装、不具合単位でチケットを作ることが出来るため、事前の議論や管理もしやすくなります。
例えば、
- 新しい機能を追加したいからIssueを新規作成します。
→ 必要に応じて担当者やラベル等を設定する。 - Issueのコメントで仕様等を議論する。
→ 問題なければ実装を進めてコミット。 - Issueをクローズする。
※クローズせずにコメント禁止とすることも出来る。
といったユースケースです。
※コミットやマージの際のプルリクエスト生成等は省略しています。
Commit連携
Commit時のコメントにチケット番号（#1 等）を含めれば、該当Issusにリンクが生成されるため、変更を追うことも容易になります。
作成画面のカスタマイズ
デフォルトのIssue作成画面はまっさらです。
リポジトリの設定からIssueテンプレートとして定義することが出来ます。
このテンプレートは誰が管理？（どこに保存される？）
該当リポジトリのmainブランチ内だね（ .github/ISSUE_TEMPLATE 配下）。テンプレートを追加・変更したいならCommit＆Pushしないとだめ。
ご参考：GitHub.comのβ機能（2023年3月時点）では、Issueの作成画面をもっと高度に（モダンに）表示する「フォーム」機能が使えます。
- 選択肢を表示できる。
- 入力必須を定義できる。
など。
ただし、Issue作成後は単なる文面です（再編集で再選択が出来るわけではない）。あくまでも、作成時に何を書けばいいのかをもっと親切に出来る機能といったところでしょうか。
他に出来ること
↓他に出来ること↓
- ファイル添付（ファイル種別や容量制限あり）
- タスクリストによる簡易的なチケットの親子管理
- Issue同士のリンク
など。
出来ないこと
Issuesは簡易的なチケット管理です。
ゆえに、
- ステータスやフィールドは増やせません。
- フィールドの制御（必須入力など）は出来ません。
※フォームを使えば部分的に制御可能です（Issue作成時限定）。 - ワークフローは設定出来ません。
※正確にはActionsでカスタマイズすれば、自動でラベル付与などは可能です。 - テーブル表示やカンバン表示は出来ません。
- sub-issueも作成出来ません。
⇒ sub-issueは2024年10月時点でβ扱いで対応可能になるようです！
そのため、プロジェクトのことをもっと細かく管理するとなると、従来はRedmineやJIRAといった、他のプロジェクト管理ツールと連携させてってパターンもありました（GitHubは外部ツール連携を豊富にサポートしています）。
けど、可能であればGitHubだけで管理したいです。
そんな要望にも応える形で登場したのが「Projects」です（だと思っています）。
Projectsについて
2022年に正式リリースされた新しい機能で、Issuesの各チケットを横断的に管理できることを主な目的にしているようです。Projects自体はオプション機能であって、使う使わないは、リポジトリの設定から選択可能です（デフォルトは”利用する”でした）。
※Classic Projectsでも同じようなことが来たのだと思いますが、本記事においてClassicの方は意識していません。
出来ることの例
複数リポジトリのIssueをProjectsのチケットに表示
例えば、次の画面におけるチケットの連携状況を説明します。
- 複数リポジトリのIssueを表示しています。
- リポジトリ未所属のチケットも表示している（Draftチケット）。
→ Draftチケットはとりあえず作成しただけで、今後任意のリポジトリに割り当てていくようなチケットです。
◇Projectsチケットの作成パターン
Project契機、Issues契機があります。
- Projectsから任意リポジトリの任意Issueを選んで割り付ける。
- Projectsで未割当のDraftチケットを作成し、後で任意のリポジトリに割り付けする。
※ 割付けの段階で、新規Issueが自動的に作成されます。 - Issueを作成し、Issue画面のProjectフィールドから任意のProjectを選択する。
※ 選択した段階で、新規チケットが自動的に作成されます。
- QProjectsとIssuesとフィールド等の連動はあるのかな？
- A
共通的なフィールドとして「タイトル」「担当者」「ラベル」などがありますが、連動して更新されました。
例えば、
- Issueのラベルを更新した場合、Projectsチケットのラベルも更新される。
- Projectsチケットのラベルを更新した場合、Issueのラベルも更新される。
ワークフロー
Projectsはワークフローがあります。
例えば
- IssueのClose契機でProjectsのチケットを完了に遷移させる。
- 完了チケットを一定期間後にアーカイブ（画面から非表示）にする。
など。
デフォルトで数種類のワークフローが有効になっており、有効/無効を簡単に設定出来ます。
表示モード
次のような表示が出来ます。
- カンバン表示
- テーブル表示（一覧表示）
- ロードマップ表示
テーブル表示
テーブル表示では、チケットのフィールドを横に並べて表示することが出来ます。もちろん表示だけではなく編集も可能です。また、カスタムフィールドとしてテキストフィールドや日付フィールド、選択フィールドなどを追加出来ます。
→ Issuesでは管理できなかったものが管理できるようになります。
カスタムフィールドの値はIssue側でも表示・変更が可能です。
ロードマップ表示
ロードマップ表示では、日付情報の可視化が出来ます。具体的にはガントチャート表示のように日付を可視化出来ます。
例えば
- 開始予定日
- 終了予定日
というカスタムフィールドを定義して、ロードマップに関連付けすると、可視化してくれます。上手く活用すれば、簡易的な日程管理をGitHubで実施できるという可能性を秘めています。
Issueは複数のProjectsに割り付け可能です
次のようなイメージです。
色々な目的のボード（Projects）を作った場合に便利ですね。
Insights（可視化）
Projectsのタスクデータを元にしたグラフ生成が可能です。
例えば、
- Issue残数
- 担当者や優先度毎のIssue数
- イテレーション毎のストーリーポイント合計数
など。自分で軸を設定出来るので、様々なグラフを生成可能です。
これはありがたい機能です。
進捗状況はここのグラフを見てください、リアルタイムで更新されます！
他に出来ること
- プルリクエストのチケットもProjectsに表示出来ます。
- テンプレートを準備出来ます。
→ 事前にカスタムフィールドを定義しておけば楽に適用できます。 - テーブル表示はグループ化も出来ます。
→ リポジトリ毎や担当者毎に表示させたりして、ドラッグ＆ドロップも出来る優れものです。
出来ないこと
例えば
- ワークフローのきめ細かい制御
- フィールドの入力必須等
は出来ません。
FAQ・雑記
- QIssues、Issueの違いは？
- A
サービス名はIssues、個々のチケットはIssue、と私は理解しています。
（どちらでも伝わるでしょう）
- QProjectsのチケットの呼び方は？
- A
公式サイトではItem、Ticket、あるいはTaskって呼ばれているのを見たことがあります。
- QProjectsのチケットに上限はあるの？
- A
1200件です。
⇒ 2024年のchangelogによると最大50000件に拡大できるとのこと。
- QConvert to issueとは？
- A
ProjectsでDraftなItemをIssuesと連携させる処理のこと。
ドラフトIssueのIssueへの変換 - GitHub Docsドラフト issue を issue に変換する方法について学習します。docs.github.com任意リポジトリを指定すると、任意リポジトリでIssueが作成され、連携させる。
◇適切な粒度とは？
→基本はチーム毎にProjectsがあってその配下に複数のリポジトリがあったほうがわかりやすいと思う。設定上は1個のIssueを複数のProjectsに割付けることも出来るけど、管理が難しそう（Projectsの目的が違うならアリ）。
◇出来ることを増やすと、シンプルさが無くなるので、一長一短といったところでしょうか。管理職によっては、厳密にフィールドを定義して指標とかを管理したいんだよっていうコントロールは、今のGitHubでは難しいと思います。（GitHubのバージョンアップ頻度は早いため、大きな要望はすぐに反映され、簡単に出来ることがもっと増えるかもしれません。）
まとめ
GitHubのIssues、Projectsに関して出来ることや出来ないことの一例をご紹介しました。
- Issueはリポジトリ単位で簡単なチケット管理が出来る。
- Projectsはリポジトリ横断の単位でチケット管理が出来て、フィールド追加、テーブルやロードマップ形式で表示（可視化）出来る。
企業内で規模が少ないうちはIssuesすら不要かもしれません。しかし利用者数の増加、複数人のレビュー等が発生するとIssuesが必須となります（もちろんPull Requestも）。
さらに複数のリポジトリがあって、全体的な状況を管理する必要がある場合に、Projectsが必要になってきます。
使い方はシンプルでわかりやすいため、GitHubを利用するなら積極的に使いたい機能の1つです。
最後までご覧いただきありがとうございました。
コメント