メインコンテンツまでスキップ

Issues

Introduction​

GitHub における issue は、プロジェクトやリポジトリに関する問題を管理する機能で、タイトル、説明、状態、ラベル、担当者、期日などの情報を含むことができます。issue は、プロジェクトの進捗状況を把握するために活用され、コードの変更や修正に結びつけられることが多く、オープンソースプロジェクトのコミュニケーションや、チーム内での課題管理、QA 作業などに幅広く活用されています。

issue 運用​

目的​

issue の記載内容を統一化した上で管理者または開発者が作業しやすくなること。​

管理者
・ 作業の把握
  -> 情報がslackやGoogle Driveなどに散らばっているとタスク状況の把握がむずかしく、
  先方からの依頼などに対する返答にかかる時間が長くなることを防ぐ
開発者
・ 修正前に情報整理を行うことで1タスク当たりの作業時間を短縮する
・ 作業成果・作業進捗が報告しやすくなること
・ 案件移動の際にタスクの進行の統一化によりすぐに作業を開始できること
管理者と開発者
・ issueを見ることで作業の現在地と過程がわかること
  -> タスク完了までの経緯が理解できること
・ 引き継ぎの担保
  -> 作業を引き継ぐ際に、作業を引き継ぐ人が進行状況を把握しやすくなり、口頭での引き継ぎの時間を短縮できること

テンプレート作成​

link: https://docs.github.com/ja/communities/using-templates-to-encourage-useful-issues-and-pull-requests/manually-creating-a-single-issue-template-for-your-repository

目的
・ issue起票者が毎回項目を記載せずに済むようにする
・ 記載する内容を統一化する
・ 項目を埋めることで起票完了となるようにする

手順​

mdの記載例(https://github.com/fox-hound-ltd/syzygy/blob/main/.github/issue_template.md)
---
name: 汎用 <!-- 複数テンプレートの場合におけるタイトル名 -->
about: Github Issue運用におけるテンプレート例 <!-- 複数テンプレートの場合における備考 -->
---

**要望**

- xxx

**タスクリスト**

- [ ] xxx

#### 期限
備考

単一テンプレート

・ issue_template.md というファイル名で作成しないと反映されない

=> sample.md という名称だと反映されない

複数テンプレート

・ ISSUE_TEMPLATE 配下に複数の.md ファイルを作成しないと反映されない

=> 1 つの.md ファイルだと反映されない

link: https://docs.github.com/ja/communities/using-templates-to-encourage-useful-issues-and-pull-requests/manually-creating-a-single-issue-template-for-your-repository#adding-an-issue-template

issue 記載内容​

1. タイトル
① カテゴリやフェーズなどを【】で囲む
  -> issue一覧で管理者と開発者がカテゴリやフェーズを判別できる
② 外部サービス(バックログなど)でチケット管理の場合はチケット番号記載
  -> 外部チケットとの紐付きを一覧で判別可能
実用例
2. 概要
issueテンプレートを下記項目で作成しておくことでissue記載内容の統一化と起票コスト削減する。

① 要望(目的)
- タスクの概要や詳細を記載する
-> バックログなどの外部サービスでチケット管理を行なっている場合は、URL等を貼っておくと便利です
-> またバックログチケットの対応の場合は、内容をそのまま引用すると漏れがなくなります

② タスクリスト
管理者と開発者どちらが記載しても良いですが、負担の都合で開発者が記載することが望ましいです。
ex. ざっくりとしたタスクリストを管理者が作成する -> 開発者が細分化する

- 要望(目的)を達成するために必要なタスクをチェックボックスでリスト化する
-> 作業内容の整理をおこない、効率よくタスクをこなすことができます
-> 報告の際にどこまで完了しているかがわかりやすくなります

- リスト化したタスクに予定工数を振る
-> 開発者自身が工数意識をすることになり、作業の見積もりが正確になります

③ 期限
個人レベルもしくは、案件に応じた期限を設定する
-> 時間的制約を設けることで、タスク完了までのスピードをあげる
-> 期限を管理者、開発者が把握しやすくなる

実用例
ヒント

1 つの issue に全てのタスクを書いてしまうと、タスクが多くなりすぎて管理が難しい場合

convert to issue の機能を使用して子 issue を作成することで issue を分離して issue ごとの役割分担を行う (下記動画参照)

3. 過程
充実していればしているほど良い。
不要になったコメントなどはhideで隠すことができるので管理者、開発者問わずメモでも残していきたい。
-> 間違った設計などは削除せずに、hideで隠すのみにしておけば圧迫せず、後から見返すことが可能

開発者目線:
  成果報告を過程に沿って話すことが可能
  コードレビュー以外のレビューが口頭ベースでなくテキストベースで可能になる
管理者目線:
  情報把握がissueにまとまることで負担軽減
  -> 情報が点在すると欲しい情報を探す時間が増えて負担になる

○ 記載観点
① 調査
  要望に対して、技術的に実現可能かどうかや調査結果や修正すべきファイルなどを記載する

② 設計
  調査した上で修正規模が大きいもしくは、複雑性が高い場合は詳細設計を記載する
  -> 設計レビューが可能になり、実作業前に考慮漏れや不安な点などを洗い出すことができ、手戻り発生を抑制する
  簡単な修正でも頭の中で設計は行なっているはずなので、設計していることの意識を持つことが大切

③ 工数策定根拠
  2.概要②のタスクリストで振った工数の根拠を記載する
  -> 管理者と開発者の想定工数のずれをなくすことができる
  -> 管理者が開発者に口頭で工数に関しての確認をする時間を削減できる
  -> 工数に問題ないかのレビューをおこなうことができ、工数が妥当かどうかを確認した上で安心して作業できる
  ex. 管理者が少ない工数で見積もったのに対して、開発者が多く見積もっている場合は、開発者の設計が不十分な可能性などが想定される

④ 先方確認状況
  仕様確認内容や返答などのやり取りを記載する
  -> 管理者が情報を把握しやすい
  ex. カヤック案件での活用はslackでissueコメントのリンクを貼って管理者に確認してもらうようなフローを採用していた

⑤ 懸念
  テキストとして残すことで、後から見返すことができる
  -> 口頭の場合は懸念事項をわすれることがあるので、テキストで残すことで懸念事項を洗い出すことができる
  また、情報の整理も兼ねることができる

⑥ 検討
  修正にあたり複数解消法がある場合に、どういった根拠でどの解消法を選択したかを記載する
  -> コミットログを追っていた人などに、なぜその解消法を選択したかを理解してもらうことができ、口頭で確認する手間を削減できる
実用例
4. ラベル
issue一覧でみたときにUIでわかりやすいようにラベルを付与することで
詳細を見ずに優先度や状況を把握できるようにする。

① 優先度を表すラベルを付与する
  P1, P2, P3など(P1 > P2 > P3の順は優先度が高い順)
  -> 案件独自の優先度などのラベルを作成することも可能
  -> github projectsも使っていれば、ラベルごとのグループ化ができるので、開発者、管理者ともに優先タスクの把握がしやすい

② 先方確認などで作業を止めている場合は「wontfix」などのラベルを付与
  -> 開発者側がタスク選択時に作業を止めていることを把握しやすい
  -> 管理者側がタスク状況を一覧で把握しやすい

③ その他
  ステージング反映待ち、本番反映待ちなど
  -> 案件特有のラベルを作成してissue一覧での状況把握をしやすくする

実用例
5. マイルストーン
フェーズやリリースなどのマイルストーン(節目, 重要ポイント)を、issueに紐付けることで
マイルストーンごとのissueが把握しやすくなり、探す時間の削減につながる
-> issue一覧から絞り込みができる

メモも行うことはできるのでマイルストーンの詳細などの記載も可能
実用例
6. アサイン
開発者はアサインする
-> 管理者や他開発者がアサイン状況を把握できる。
-> 開発者は影響範囲の連携などを他開発者と行うことができ、管理者は手隙の開発者や誰がどのタスク作業中かを把握できる
ex. カヤックではタスクをとるときにアサインして作業していた

実用例
7. PRと紐付け
PRに紐付けをすることでissueをPRマージによって自動クローズしたりできる

PRの概要欄に以下記載を行うことで紐付けや自動クローズを設定できる

issue: `issueURL`
=> リンクさせる
close: `issueURL`
=> マージ後に自動で issue を閉じる

実用例
8. github projects紐付け
カヤック案件で導入中
-> issueを管理でき、期限(deadline)や紐づけられたPR(linked pull requests)をテーブルのようなUI上で管理できるようにできる
※ 詳細はgithub projectsのドキュメントを参照

開発者目線:
-> 次の優先タスクを取りやすい
-> 期日が迫っているが着手は早い方がよいタスクを把握しやすい
管理者目線:
-> 管理者側がタスク状況を把握しやすい

実用例

issue 起票から完了までの流れ(一例)​

注記

案件ごとに反映の方法はかわるため案件独自にカスタマイズしてください。