ラベルとマイルストーン
プロジェクトの進捗管理において、IssueやPull Requestが増えるほど全体像の把握が難しくなります。GitHubが標準で提供するラベルとマイルストーン機能を適切に使うことで、この問題を体系的に解決できます。本記事では、これらの機能の仕様と実践的な活用方法を解説します。
1. ラベル機能の本質
ラベルは、Issue、Pull Request、Discussionを分類するためのメタデータです。リポジトリスコープで管理され、他のリポジトリには影響を与えません。これにより、各プロジェクトの特性に応じた分類体系を構築できます。
1.1 デフォルトラベルの設計思想
GitHubは新規リポジトリ作成時に、以下の9つのデフォルトラベルを自動生成します。
| ラベル名 | 用途 | 使用例 |
|---|---|---|
bug |
予期しない問題や意図しない動作を示す | クラッシュ、誤った計算結果、表示崩れ |
documentation |
ドキュメントの改善や追加が必要 | README不足、APIドキュメント未整備 |
duplicate |
類似のIssue、Pull Request、Discussionを示す | 既存Issue #123と同じ内容 |
enhancement |
新機能のリクエストを示す | 新しいAPI追加、UIコンポーネント拡張 |
good first issue |
初めての貢献者に適したIssueを示す | 小規模なバグ修正、タイポ修正 |
help wanted |
メンテナーが支援を求めている | レビュー依頼、設計相談 |
invalid |
もはや関連性のないものを示す | 重複、誤報告、仕様外 |
question |
追加情報が必要なものを示す | 再現手順不明、環境情報不足 |
wontfix |
作業を継続しないことを示す | 仕様として意図した動作、対応範囲外 |
これらは後から編集・削除が可能です。組織のオーナーは、組織全体のデフォルトラベルをカスタマイズすることもできます。
注目すべきはgood first issueラベルです。このラベルが付与されたIssueは、リポジトリのcontributeページに自動的に表示されます。これにより、新規コントリビューターへの導線が明確になります。
1.2 ラベルの操作
ラベルの作成、編集、削除には、リポジトリへのwrite権限が必要です。
作成手順:
- リポジトリのIssuesまたはPull requestsタブに移動
- 「Labels」ボタンをクリック
- 「New label」ボタンをクリック
- ラベル名、説明、カラー（16進数）を入力
- 「Create label」をクリック
編集手順:
- Labelsページで編集したいラベルの「Edit」をクリック
- 情報を修正
- 「Save changes」をクリック
削除手順:
- Labelsページで削除したいラベルの「Delete」をクリック
- 削除を確認
ラベルを削除すると、そのラベルが付与されていたすべてのIssueとPull Requestから削除されます。
1.3 ラベルの適用
ラベルの適用には、リポジトリへのtriageアクセス権限が必要です。これはwrite権限よりも限定的な権限で、Issueの管理に特化しています。
適用手順は以下の通りです。
- 対象のIssue、Pull Request、またはDiscussionに移動
- 右サイドバーの「Labels」をクリック
- 適用したいラベルを選択
2. マイルストーン機能の設計
マイルストーンは、複数のIssueやPull Requestをグループ化し、その進捗を可視化する機能です。スプリントやリリースサイクルなど、時間軸で区切られた開発フェーズの管理に適しています。
2.1 マイルストーンで確認できる情報
マイルストーンページでは、以下の情報が一元管理されます。
- ユーザー提供の説明文: プロジェクト概要、関連チーム、予定期日などの情報
- 期日: マイルストーンの完了予定日
- 完了率: 進捗状況のパーセンテージ
- 関連するIssueとPull Requestの数: オープン・クローズ別
- 関連するIssueとPull Requestのリスト: 実際の作業項目
2.2 マイルストーンの作成と編集
作成手順:
- リポジトリのIssuesまたはPull requestsタブに移動
- 検索フィールド横の「Milestones」をクリック
- 「New Milestone」ボタンをクリック
- タイトル、説明（Markdown記法可）、期日を入力
- 「Create milestone」をクリック
編集手順:
- Milestonesページで編集したいマイルストーンの「Edit」をクリック
- 情報を修正
- 「Save changes」をクリック
削除手順:
- Milestonesページで削除したいマイルストーンの「Delete」をクリック
- 削除を確認
重要な点として、マイルストーンを削除してもIssueやPull Requestは削除されません。関連付けが解除されるだけです。
マイルストーンの説明欄ではMarkdown記法が利用できるため、以下のような構造化されたプロジェクト情報を記述できます。
## 目標
v2.0リリースに向けた主要機能の実装
## スコープ
- ユーザー認証機能の刷新
- API v2の実装
- パフォーマンス改善
## 担当チーム
- @backend-team
- @frontend-team
## 期日
2025-12-31
2.3 IssueとPull Requestの関連付け
マイルストーンへの関連付けは、以下の手順で行います。
- リポジトリのIssuesまたはPull requestsタブに移動
- 関連付けたい項目のチェックボックスを選択（複数選択可能）
- リスト上部の「Milestone」ドロップダウンメニューを選択
- 「Filter milestones」フィールドで既存マイルストーン名を入力
- 該当するマイルストーン名をクリック
2.4 優先順位の管理
マイルストーン内のIssueとPull Requestは、優先順位を設定できます。
操作方法は直感的です。
- マイルストーンページにアクセス
- IssueまたはPull Requestのチェックボックス左側をクリック
- 新しい位置にドラッグ&ドロップ
制約事項: マイルストーン内にオープン状態のIssueが500件を超える場合、優先順位付け機能は利用できません。
この制約に直面した場合、以下の対応を検討します。
- マイルストーンの分割: 「v2.0-Phase1」「v2.0-Phase2」のように、時系列や機能単位で分割
- Issueのクローズ: 完了済みだが未クローズのIssueを整理
- 別リポジトリへの移動: 独立性の高い機能を別リポジトリで管理
3. フィルタリングによる効率的な検索
3.1 マイルストーンによるフィルタリング
マイルストーンに関連付けられたIssueやPull Requestは、以下の方法でフィルタリングできます。
UIベースの方法:
- リポジトリのIssuesまたはPull requestsタブに移動
- 「Milestones」を選択してマイルストーン一覧を表示
- 目的のマイルストーンを選択
検索構文の利用:
検索バーでmilestone:"マイルストーン名"という構文を使用できます。
例: milestone:"v2.0リリース"
フィルタ選択をクリアするには、「Clear current search query, filters, and sorts」をクリックします。
3.2 GitHub CLIでのフィルタリング
コマンドラインから操作したい場合、GitHub CLIが利用できます。
# Issueのフィルタリング
gh issue list --milestone "v2.0リリース"
# Pull Requestのフィルタリング
gh pr list --milestone "v2.0リリース"
4. 進捗の可視化
マイルストーンの進捗状況を確認する手順は以下の通りです。
- リポジトリのIssuesまたはPull requestsタブに移動
- 右上の「Milestones」をクリック
- 詳細を確認したいマイルストーンを選択
4.1 マイルストーンページで確認できる指標
マイルストーンページでは、以下の情報が視覚的に表示されます。
進捗バー
- 完了率がパーセンテージで表示
- クローズ済みとオープンのIssue/Pull Requestの割合が視覚化
数値情報
- オープンのIssue数
- クローズ済みのIssue数
- オープンのPull Request数
- クローズ済みのPull Request数
期日情報
- 設定された期日までの残り日数
- 期日超過の場合は警告表示
これらの情報により、スプリント計画やリリース判断の重要な指標が得られます。例えば、期日まで5日で完了率が60%の場合、スコープ調整やリソース追加を検討できます。
5. 実践的な活用例
5.1 ラベル体系の設計
デフォルトラベルに加えて、以下のようなカスタムラベルを追加することで、より詳細な分類が可能になります。
# カスタムラベルの例
labels:
- name: "priority: high"
color: "d73a4a"
description: "優先度が高い作業"
- name: "priority: medium"
color: "fbca04"
description: "優先度が中程度の作業"
- name: "priority: low"
color: "0e8a16"
description: "優先度が低い作業"
- name: "area: frontend"
color: "1d76db"
description: "フロントエンド関連"
- name: "area: backend"
color: "5319e7"
description: "バックエンド関連"
- name: "area: infrastructure"
color: "fbca04"
description: "インフラストラクチャ関連"
5.2 マイルストーン構成例
6. まとめ
GitHubのラベルとマイルストーン機能は、シンプルでありながら強力なプロジェクト管理ツールです。
ラベルは分類と検索性を提供し、マイルストーンは時間軸での進捗管理を実現します。これらを組み合わせることで、以下が達成できます。
- IssueとPull Requestの体系的な整理
- プロジェクト進捗の定量的な把握
- チーム内での情報共有の効率化
- 新規コントリビューターへの明確な導線
重要なのは、これらの機能がGitHubの標準機能であり、追加のツールやサービスを必要としない点です。既存のワークフローに自然に組み込むことができます。
プロジェクトの規模や特性に応じてラベル体系とマイルストーン構成をカスタマイズすることで、より効果的なプロジェクト管理が実現します。