#12 GitHubラベル設計: 優先度・階層・自動化 - Python OSS開発記録
karrinn
著者
Issueが増えてくると「どれが優先？」「これは親Issue？子Issue？」と管理が大変になりますよね。
体系的なラベル設計で、情報整理と自動化を両立できます。今回はwagtail-reusable-blocksでの設計を振り返ります。
KEY TAKEAWAYS
この記事でわかること
- ラベル設計の5カテゴリ（優先度・階層・タイプ・タスク・自動化）
- parent/child/atomic階層の使い分け
- Release Drafter連携（トピック#9）と色分け戦略
用語の定義
TERM 01
ラベル (Labels)
GitHub IssueとPRに付けるタグ。検索・フィルタリング・自動化に使用。色・名前・説明を自由に設定可能。複数ラベル同時付与可。
TERM 02
親Issue (Parent Issue)
複数の子Issueに分解される大きなタスク。「parentラベル」で識別。全体像を示し、進捗管理の起点になる（トピック#13で詳説）。
TERM 03
アトミックIssue (Atomic Issue)
これ以上分解できない最小単位のタスク。「atomicラベル」で識別。1人・1PR・1日以内で完結する粒度が目安。
TERM 04
セマンティックラベル (Semantic Labels)
意味を持つラベル設計。命名規則（priority:high等）と色分けで視認性向上。機械可読・自動化可能なラベル体系。
ラベル設計の原則
wagtail-reusable-blocksでは、5つのカテゴリに分けてラベルを体系化しています。プレフィックスを使った命名規則と一貫した色分けで、視認性と自動化を両立させています。
5つのラベルカテゴリ
1. 優先度ラベル
priority:xxx
- critical（赤）
- high（オレンジ）
- medium（黄）
- low（緑）
2. 階層ラベル
Issue構造
- parent（紫）
- child（水色）
- atomic（緑）
3. タイプラベル
変更の種類
- enhancement（水色）
- bug（赤）
- documentation（青）
4. タスクラベル
作業内容
- implementation, review, issue-management
- cleanup, organization, decomposition
- documentation-org
5. 自動化ラベル
システム付与
- automation（緑）← 自動化システムが付与
設計のポイント
カテゴリごとに命名規則と色を統一することで、視認性と機械可読性を両立。
例: priority:xxx → 赤〜緑のグラデーション、階層ラベル → 紫系統
Release Drafter（トピック#9）のautolabelerとも連携。
参考: Sane GitHub Labels - Medium, Using labels and milestones - GitHub Docs
カテゴリ1: 優先度ラベル（priority:xxx）
4段階の優先度で、作業の緊急度を明示します。色のグラデーションを使うことで、Issueリストを一目見ただけで優先度がわかるようになります。
4つの優先度レベル
| ラベル | 色 | 説明 | 使用例 |
|---|---|---|---|
| priority:critical | #B60205 | 即座に対応必要 | 本番障害、セキュリティ脆弱性 |
| priority:high | #D93F0B | 高優先度 | 重要機能のバグ、次リリースの必須機能 |
| priority:medium | #FBCA04 | 通常優先度 | 一般的な機能追加、軽微なバグ |
| priority:low | #0E8A16 | 低優先度 | Nice to have、リファクタリング |
色のグラデーション戦略
視覚的に優先度を判断できるよう、赤→緑のグラデーションを採用しています:
- 赤系 → 緊急（critical）
- オレンジ系 → 高優先（high）
- 黄色系 → 通常（medium）
- 緑系 → 低優先（low）
視覚効果
Issueリストで一目で優先度がわかります:
Release Drafterとの連携
トピック#9で設定したRelease Drafterは、priority:criticalラベルを検出してmajorバージョンアップを推定します。
priority:critical→ major（1.0.0 → 2.0.0）enhancement→ minor（0.1.0 → 0.2.0）bug→ patch（0.1.0 → 0.1.1）
version-resolver: major: labels: - "priority:critical" minor: labels: - "enhancement" - "implementation" patch: labels: - "bug" - "documentation"
カテゴリ2: 階層ラベル（parent/child/atomic）
Issueの粒度を3段階で管理し、Issue分解と進捗管理を明確化します（詳細はトピック#13）。
3階層の役割
| ラベル | 色 | 役割 | 粒度の目安 |
|---|---|---|---|
| parent | #8B4789 | 複数の子Issueに分解される親Issue | 1週間〜数週間、複数人 |
| child | #C5DEF5 | 親Issueから分解された子Issue | 1〜3日、1〜2人 |
| atomic | #00C851 | これ以上分解不要な最小単位 | 数時間〜1日、1人・1PR |
階層の使い分け例
例: 「Reusable Block機能の実装」
- parent Issue #10: Reusable Block機能の実装
→ 大きな機能、複数週間かかる見込み - child Issue #11: ReusableBlockモデルの実装
→ #10の子Issue、2〜3日で完結 - child Issue #12: Slotシステムの実装
→ #10の子Issue、2〜3日で完結 - atomic Issue #13: READMEにインストール説明追加
→ 分解不要、1時間で完結、1PR
トピック#13で詳説: 親Issueからアトミックな子Issueへの分解方法、Sub-issue/Blocked by設定はトピック#13・#14で解説します。
カテゴリ3: タイプラベル
変更の種類を示し、Release Drafter（トピック#9）のautolabelerと連携します。ブランチ名から自動でラベルが付与されるので、手動でのラベル付けが不要になります。
3つのタイプ
| ラベル | 色 | 説明 | 対応ブランチ |
|---|---|---|---|
| enhancement | #A2EEEF | 新機能追加 | feature/xxx |
| bug | #D73A4A | バグ修正 | fix/xxx |
| documentation | #0075CA | ドキュメント改善 | docs/xxx |
Release Drafter autolabelerとの連携
トピック#9で設定したautolabelerは、ブランチ名から自動でラベル付与します:
feature/xxx→ enhancementfix/xxx→ bugdocs/xxx→ documentation- → Release Drafterがこれを検出してリリースノート分類
autolabeler: - label: "enhancement" branch: - "/feat\\/.+/" - "/feature\\/.+/" - label: "bug" branch: - "/fix\\/.+/" - "/bugfix\\/.+/" - label: "documentation" branch: - "/docs\\/.+/"
カテゴリ4: タスクラベル（作業内容の明示）
具体的な作業内容を示すラベル群です。プロジェクト運営に必要な様々なタスクを分類することで、「今何をすべきか」が明確になります。
7つのタスクラベル
| ラベル | 色 | 説明 |
|---|---|---|
| implementation | #1D76DB | 実装タスク（コード書く） |
| review | #FBCA04 | レビュータスク（PRレビュー） |
| issue-management | #D93F0B | Issue管理タスク |
| cleanup | #5319E7 | ブランチクリーンアップ |
| organization | #0052CC | プロジェクト整理 |
| decomposition | #9C27B0 | Issue分解タスク |
| documentation-org | #1E90FF | ドキュメント整理 |
カテゴリ5: 自動化ラベル（automation）
システムが自動生成したIssue/PRを識別するラベルです。フィルタリングで除外することで、手動で作成したIssueだけを確認できます。
自動化ラベル
ラベル詳細
- automation
- 色:
#0E8A16（緑） - 説明: Issue/PR created by automation
- 用途: GitHub Actions等が自動生成したIssue/PRに付与
使用例
自動生成されるIssue/PR:
- Dependabot PRに自動付与
- GitHub Actionsで生成したIssue
- 定期実行botによるPR
- → フィルタリングで除外可能
ラベル設定方法
GitHubのWeb UIまたはgh CLIでラベルを作成・管理できます。gh CLIを使えば、スクリプトで管理でき、他リポジトリにも簡単に適用できるのでおすすめです。
gh CLIでの一括作成
gh CLIを使えば、ラベルを一括作成できます:
- スクリプトで管理可能
- 他リポジトリにも簡単に適用
- バージョン管理できる
- Web UIより効率的
# 優先度ラベル作成 gh label create "priority:critical" \ --description "Requires immediate attention" \ --color "B60205" gh label create "priority:high" \ --description "High priority" \ --color "D93F0B" # 階層ラベル作成 gh label create "parent" \ --description "Parent issue with child issues" \ --color "8B4789" gh label create "atomic" \ --description "Smallest unit issue" \ --color "00C851"
Pro Tip: ラベルの一括コピー
gh label clone owner/repo コマンドで、既存リポジトリからラベルを一括コピーできます。新しいプロジェクトを始めるときに便利です。
OSS vs 企業プロジェクト: ラベル設計の違い
プロジェクトの性質によって、最適なラベル設計は異なります。OSSではシンプルさを重視し、企業プロジェクトではチーム特化の詳細管理を行うことが多いです。
OSS: シンプル・明確・自動化重視
wagtail-reusable-blocksでは、外部コントリビューターが迷わないよう、シンプルなラベル体系を採用しています。
OSSラベル設計のポイント
- 英語で統一: 国際的なコントリビューター対応
- 説明文を丁寧に: 「priority:high - High priority」だけでなく、使用例も記載
- 色分けの一貫性: priority系は赤〜緑、階層系は紫系統など、ルールを明確に
- autolabeler活用: ブランチ名から自動付与（トピック#9参照）
- ドキュメント化: CONTRIBUTING.mdでラベルの使い方を説明
外部コントリビューター視点:
「このIssueはどの優先度？」「これは親Issue？」が一目でわかるラベル設計。
迷わせない = コントリビューションのハードルを下げる。
企業: チーム特化・詳細管理
企業プロジェクトでは、チーム固有の運用に合わせたラベル追加が有効です。
企業で追加されることが多いラベル
チーム・担当者ラベル
team:frontend,team:backend,team:infra← 担当チーム明示needs:design,needs:legal← 他部署確認必要blocked,waiting-on:xxx← ブロッカー明示
ビジネス関連ラベル
customer-request← 顧客要望revenue-impact← 売上影響ありcompliance← コンプライアンス関連tech-debt← 技術的負債
リリース管理ラベル
milestone:v1.0,milestone:v2.0← リリースバージョンrelease:blocker← リリース前に必須sprint:2024-12← スプリント管理
注意: ラベル過多の罠
ラベルが多すぎると逆効果
ラベルは必要最小限に。50個も100個もあると、どれを付ければいいか迷います。
wagtail-reusable-blocksの18個が参考値。企業でも20〜30個程度に抑えるのが理想。
ルール: 3ヶ月使われていないラベルは削除検討。
定期的に見直し、実際に使われているラベルだけ残す。
参考: Best Practices for Maintainers - Open Source Guides, 10 GitHub Labels Best Practices - CLIMB
よくある質問
A: 20〜30個程度が目安です。
wagtail-reusable-blocksは18個。必要最小限に抑えることが重要です。
50個も100個もあると、「どれを付ければいいの？」と迷ってしまいます。
定期的に見直し、使われていないラベルは削除してみてください。
A: はい、推奨します。
例: priority:highenhancementatomic
→ 「高優先度の新機能で、アトミックIssue」と一目でわかります。
カテゴリが異なるラベルは併用OK（優先度 + タイプ + 階層）。
A: カテゴリごとに色系統を統一すると見やすいです。
wagtail-reusable-blocksの例:
・優先度ラベル: 赤→緑のグラデーション（視覚的に緊急度がわかる）
・階層ラベル: 紫系統（parent: 濃紫、child: 水色、atomic: 緑）
・タイプラベル: 水色〜青系統
一貫性が最も重要。色がバラバラだと視認性が下がります。
A: プロジェクト規模によります。
小規模プロジェクト（Issue数が少ない）なら不要かもしれません。
中規模以上（Issue数が50以上）なら、親/子/アトミックの階層があると管理しやすいです。
wagtail-reusable-blocksは、Issue分解を前提とした設計なので採用（トピック#13参照）。
A: プロジェクトによります。
OSS: 英語推奨（国際的なコントリビューター対応）
社内プロジェクト: 日本語でもOK（チームが日本人のみなら見やすい）
ただし、Release Drafter等のツールは英語ラベル前提の場合が多いです。
wagtail-reusable-blocksは英語で統一。
A: はい、gh CLIで簡単にコピーできます。
gh label clone owner/repo で一括コピー可能です。
または、GitHub Label Syncなどのツールを使えば、YAML定義から同期可能。
wagtail-reusable-blocksのラベル設計を他プロジェクトに適用するのもおすすめです。
参考: GitHub Label Sync, Best Practices for Using GitHub Issues - Rewind
まだコメントはありません。最初のコメントを残しませんか？