第9章 Issue で TODO/バグを管理する¶

この章で学ぶこと ¶

GitHub Issue の役割と動機
gh issue コマンドで Issue を作る・見る・閉じる
Markdown とチェックボックスリスト
コミットメッセージで Issue を自動クローズする

動機・背景 ¶

スクリプトを書きためていくと、「ここの引数名を直したい」「あの機能を足したい」「先週まれに再現したバグの原因が分からない」といった細かなメモが次々と溜まっていきます。これらをテキストファイルやチャットの DM に貼り付けてしまうと、後から検索しづらく、コードのどの状態に対する話だったのかも分からなくなりがちです。

Issue を使えば、そうした TODO・バグ報告・将来やりたいことを、コードと同じリポジトリに履歴付きで残せます。1 人で運用する場合でも「将来の自分への伝言」として有効ですし、同僚に見せるときも URL を 1 本送るだけで状況を共有できます。Issue は「あとでやる」をきちんと残すための、もっとも軽量な仕組みです。

最初の Issue を作る ¶

gh issue create --title "READMEに使い方を追記する" --body "現状READMEはタイトルのみ。具体的な利用手順を書く。"

対話モードを使うなら:

gh issue create

題名・本文を順に聞かれます。本文では Markdown が使えるので、見出し・箇条書き・コードブロックを自由に書けます。

期待出力:

https://github.com/<your-id>/my-scripts/issues/1

Issue 一覧を見る ¶

gh issue list

期待出力:

Showing 1 of 1 open issue in <your-id>/my-scripts

ID   TITLE                              LABELS  UPDATED
#1   READMEに使い方を追記する             ...     2 minutes ago

Issue の中身を見る ¶

gh issue view 1

ブラウザで開く場合:

gh issue view 1 --web

ラベルを付ける ¶

GitHub には bug / enhancement / question / documentation などの組み込みラベルがあらかじめ用意されており、Issue を分類するのに使えます。

新規 Issue にラベルを付ける:

gh issue create --title "起動が遅い" --body "10秒ほどかかる" --label "bug"

既存 Issue にラベルを後付け:

gh issue edit 2 --add-label "bug"

チェックボックスリスト ¶

Issue 本文に Markdown のチェックボックス (- [ ]) を書くと、ブラウザで GUI のチェックボックスとして表示され、クリックで状態を切り替えられます。

## やること
- [ ] 利用例を書く
- [ ] 必要な前提環境を書く
- [ ] よくあるエラーを書く

Tip

チェックボックスはブラウザでクリックするだけで [ ] ↔ [x] を切り替えられます (権限のあるユーザーが)。タスク管理に便利。

コミットで Issue を自動クローズする ¶

GitHub には**「Closing keywords」** という仕組みがあり、コミットメッセージや PR 説明に以下のキーワード + Issue 番号を書くと、デフォルトブランチに反映された時点で Issue が自動的に閉じます:

キーワード	例
`Fixes #N`	`Fixes #1`
`Closes #N`	`Closes #1`
`Resolves #N`	`Resolves #1`

実際に試す:

Add-Content -Encoding utf8 -Path README.md -Value "## 使い方"
Add-Content -Encoding utf8 -Path README.md -Value ""
Add-Content -Encoding utf8 -Path README.md -Value 'スクリプトを実行する: `./script.ps1`'

注釈

PowerShell の文字列はシングルクォート ('...') で囲むと ` (バッククォート) のエスケープが不要になり、Markdown のインラインコード記法 (`code`) を素直に書けます。

git add README.md
git commit -m "add usage section to README

Fixes #1"
git push

ブラウザで Issue #1 を開くと Closed になっていることを確認:

gh issue view 1

期待出力 (抜粋):

state:  CLOSED

注釈

自動クローズが起きる条件: コミットがデフォルトブランチ (本書では main) に push されること。プルリクエスト経由なら PR がマージされた瞬間。フィーチャーブランチへの push では閉じません (将来章で扱います)。

閉じた Issue を見る ¶

gh issue list --state closed
gh issue list --state all

手動で Issue を閉じる ¶

gh issue close 2 --comment "自動化対象外と判断"

ハンズオン課題 ¶

README に書きたい改善点を 3 つ洗い出し、それぞれを Issue として作成 (ラベル enhancement を付ける)
3 つのうち 1 つに対応するコミットを Closes #N を含めて push し、ブラウザで Closed になることを確認
gh issue list --state all --label enhancement で対象 Issue が一覧されることを確認

まとめ ¶

Issue は TODO・バグ・将来の自分への伝言を残す場所
gh issue create / list / view / close で CLI 完結
コミットメッセージに Fixes #N を書くと デフォルトブランチへの push でクローズされる
ラベルとチェックボックスで整理する