GitHub issueについてまとめています。
GitHub issueは、リポジトリの課題管理をおこなう機能
Issueとは問題や課題という意味。GitHubのIssues機能は、プロジェクトやソースコードの課題管理をするための機能です。
ソースコードやPull Request、変更履歴などを課題と紐付けて管理するんですね。作業の目的、変更意図がIssuesで把握できるというわけです。
実際のIssueはどのように使うのか見てみましょう。 Issuesは、リポジトリのページからIssuesをクリックすると確認できます。
以下は、書籍の誤植などをIssuesで管理しているリポジトリです。日本語も問題なく使えています。
参考）YutaroOgawa/pytorch_advanced: 書籍「つくりながら学ぶ! PyTorchによる発展ディープラーニング」の実装コードを配置したリポジトリです
GitHubのIssue機能の使い方
Issueは、コメントのつけられる掲示板のような機能を持っています。
Issuesの画面から「New Issue」ボタンで、Issueを追加できます。以下のようにタイトルと本文を入力します。マークアップ言語による、簡単な文字修飾機能があり、ヘッダー、太字、斜字、引用、コード、リンク、箇条書き、チェックリストなどのほか、特定のメンバーを宛先に指定したり、関連するissueやpull requestを記述する機能もあります。
複数人で使う場合、issueは完全フリーフォーマットで記述するよりも、テンプレート機能を使って、ある程度文章フォーマットを統一したほうが良いでしょう。
例えば、バグ報告なら、どんな不具合が出るか、不具合の再現方法、正しい動作はなにか、などを記述するようにし、例文を添えると、メンバーも書きやすいでしょう。
関連）リポジトリ用に Issue テンプレートを設定する – GitHub Docs
Issueにはメンバーによるコメントが付けられます。画面右に、担当者アサイン、ラベル、プロジェクト、マイルストーン、プルリクエストとの紐付けを設定する機能があります。
Issueの画面で使える機能について紹介しましょう。
Assignee（アサイニー）は、担当者を割り当てる機能です。誰が担当なのか明確にするんですね。Issueの一覧画面ではアイコンがズラリと並ぶので、誰がどの程度作業をかかえているのかがわかります。
ただし、Assigneeには１つのIssueに1人の担当者をアサインする１：１のルールになっていて、複数人の割当はできません。
Assigneeを自動割当するよう工夫されているかたもいます。以下のリンクは、Pull Request時にBotを連携させて、Pull Request担当者を自動的にAssigneeに設定する例です。Aut Assignというツールを使っています。
参考）Auto AssignでPullRequestのreviewers, assigneesを自動割り当てする – ひと夏の技術
ラベルはIssueを分類するためのものです。Issueを作成し、ラベルを指定します。GitHubでは、デフォルトで以下のラベルが用意されています。編集してラベルを日本語に書き換えたり、色を変更することが可能です。
- bug …バグ
- duplicate…この問題またはプルリクエストは既に存在します。
- enhancement …新機能またはリクエスト
- good first issue…新規参入者に最適
- help wanted…助けを求む
- invalid…正しくありません
- question…詳細情報が必要
- wontfix…動作しません
以下のリンクは、デフォルトのラベルを直感的にわかりやすくするために、絵文字と和訳を付ける例です。bugには「バグ」絵文字として、芋虫のマークを採用するなど工夫がされています。
GitHubのデフォルトラベルを和訳 + 絵文字付加 – Crieit
実際の日本の開発現場で使われているラベルが知りたい…というあなたは、こちらを参照してください。表示順を指定するためのラベルのネーミングルールと、具体的な26のラベル、実際の運用の流れが解説されています。
参考）GitHub の Issue 運用が助かるラベル 26 個 #Zaim｜watura｜note
Projectは、現在作業中のIssueの進行状況をカラムごとに分類して一覧することができます。カンバン機能とも呼ばれる機能です。
関連）GitHubに待望のカンバン機能「Project」ができたので、即座に使ってみた話 – Qiita
以下は、Go言語のプロジェクトのGo Release Teamのカンバンです。
このプロジェクトでは、Planned（計画済）、In Progress（進行中）、Done（完了）の３つのカラムでカンバンを作成しています。作業のステータスで分類しているイメージですね。
それぞれのカラムに表示されているcardは、ドラッグ＆ドロップで別のカラムに移動が可能です。
Milestoneは、Issueに締め切りを設定する機能です。Milestoneとして、大きめの目標と期日を設定して、複数のIssueを紐付けていきます。
以下は、Go言語のMilestoneです。
Milestonesには、リリースのバージョンのほか、gopls（Language Server。コードの自動フォーマットやエラー分析、修正案、補完などをおこないます）、Backlog（あとでやる予定）、Unreleased（リリースしないIssue）などが設定されていて、緑のグラフで進捗が確認できます。
Linked pull requestは、issueとpull requestの紐付け情報です。ローカル環境で変更を加えたブランチをリモートリポジトリにプッシュする際にpull requestとissueの紐付けを設定できるんですね。
紐付けられたプルリクエストをマージし、closeするとissueも同時にcloseすることができます。
issueを端末のCLIツールから作成する方法
issueは、GitHubのサイトにログインして作成することができますが、GitHub公式のCLIツール、ghを使うと、issueの一覧取得やコマンドラインからの作成が可能です。
【関連記事】
▶GitHubへのLogin方法 CLIツールを使ってパスワードなしでGit操作可能
以下は、端末からghコマンドでissue listを表示する例です。ローカル環境にcloneしたリポジトリのディレクトリで実行します。
$ gh issue list 1189 OPEN How to define specific version on link 2021-06-23 04 :39:28 +0000 UTC 1187 OPEN How to use Rounded from`npm install material-design-icons` 2021-06-10 02:14:39 +0000 UTC 1186 OPEN Res 2021-06-04 09:30:28 +0000 UTC 1185 OPEN sensors icon doesn't exist in flutter 2021-06-26 09 :06:21 +0000 UTC 1184 OPEN Icons 2021-05-30 22:46:59 +0000 UTC
以下は、ローカル環境からissueを作成する例です。ダブルクォーテーションで囲むことで、改行を使用することも可能です。作成後、gh issue listで作成したissueを確認しています。
$ gh issue create --title "はじめてのissue " --body " ダブルクォーテーションで改行が 可能です。 " Creating issue in user1/samplex https://github.com/user1/samplex/issues/2 $ gh issue list Showing 1 of 1 open issue in user1/samplex #2 はじめてのissue less than a minute ago
その他、Assignee、Label、Project、Milestone、Pull Requestへの紐付けもCLI上から実行できます。
まとめ
- GitHubのissueは、リポジトリの課題管理機能
- Assignee、Label、Project、Milestone、Pull Requestへの紐付けなどの機能あり
- GitHubの公式CLI、ghを使用すればターミナルからissuの確認や作成が可能
