GitHub Issue・PR の文字数設計ガイド
GitHub の Issue や Pull Request (PR) は、ソフトウェア開発チームのコミュニケーション基盤です。適切な文字数で書かれた Issue は問題の理解を早め、簡潔な PR 説明文はコードレビューの効率を高めます。一方で、情報が不足した Issue は何度もやり取りが発生し、冗長な PR 説明文は読まれません。本記事では、GitHub の各要素における推奨文字数と、開発チームの生産性を高める書き方テクニックを解説します。
GitHub の各要素の推奨文字数
| 要素 | 文字数制限 | 推奨文字数 | ポイント |
|---|---|---|---|
| Issue タイトル | 256 文字 | 30〜80 文字 | 問題を一言で特定できる |
| Issue 本文 | 65,536 文字 | 200〜1,000 文字 | 再現手順と期待動作を含む |
| PR タイトル | 256 文字 | 30〜80 文字 | 変更内容を端的に |
| PR 説明文 | 65,536 文字 | 200〜800 文字 | 変更理由と影響範囲 |
| コミットメッセージ (1 行目) | 制限なし | 50〜72 文字 (英語) | 変更の要約 |
| コミットメッセージ (本文) | 制限なし | 100〜500 文字 | 変更の詳細と理由 |
| コードレビューコメント | 65,536 文字 | 30〜200 文字 | 具体的な改善提案 |
| ラベル名 | 50 文字 | 5〜20 文字 | 分類が一目でわかる |
コミットメッセージの 1 行目を 72 文字以内に収めるのは、Git の慣習に基づいています。`git log --oneline` で表示した際に途切れず読めるようにするためです。日本語の場合は全角文字が 2 バイト扱いになるため、35〜50 文字程度が目安になります。
効果的な Issue の書き方
バグ報告の Issue は、以下の構成で書くと開発者が迅速に対応できます。
- タイトル (30〜80 文字): 「[Bug] ログイン画面でメールアドレス入力後にクラッシュする」のように、問題の種類と概要を含めます
- 環境情報 (50〜100 文字): OS、ブラウザ、アプリバージョンなど再現に必要な環境情報
- 再現手順 (100〜300 文字): 番号付きリストで手順を記載。「1. ログイン画面を開く 2. メールアドレスを入力 3. パスワード欄をクリック 4. アプリがクラッシュする」
- 期待動作 (30〜80 文字): 「パスワード欄にフォーカスが移動し、入力可能になること」
- 実際の動作 (30〜80 文字): 「アプリがクラッシュし、ホーム画面に戻される」
- スクリーンショット・ログ: テキストでは伝わりにくい情報を補完
この構成に従うと、合計 240〜640 文字の Issue が完成します。機能要望の Issue は、背景 (100〜200 文字) + 提案内容 (100〜300 文字) + 期待される効果 (50〜100 文字) の構成が効果的です。
PR 説明文のベストプラクティス
PR 説明文は、レビュアーが変更内容を理解するための最も重要な情報源です。
- 変更の概要 (50〜150 文字): 何を変更したかを 1〜2 文で述べます
- 変更の理由 (50〜150 文字): なぜこの変更が必要かを説明します。関連する Issue 番号をリンクします
- 変更の詳細 (100〜300 文字): 技術的な変更点を箇条書きで列挙します
- テスト方法 (50〜150 文字): どのようにテストしたかを記載します
- 影響範囲 (30〜100 文字): この変更が他の機能に与える影響を記載します
コードレビューコメントの文字数
コードレビューのコメントは、建設的で具体的であることが重要です。
| コメントの種類 | 文字数目安 | 例 |
|---|---|---|
| 承認コメント | 10〜30 文字 | 「LGTM。きれいな実装です。」 |
| 軽微な指摘 | 30〜80 文字 | 「nit: 変数名を isValid に変更すると意図が明確になります」 |
| 改善提案 | 50〜200 文字 | 具体的なコード例を含む改善提案 |
| 質問 | 30〜100 文字 | 「この処理が必要な理由を教えてください」 |
| ブロッキング指摘 | 80〜300 文字 | セキュリティやパフォーマンスの問題点と修正案 |
コードレビューでは、指摘の重要度を明示するプレフィックスが有効です。「nit:」(些細な指摘)、「suggestion:」(提案)、「blocker:」(マージ前に修正必須) のように分類すると、レビュイーが優先順位を判断しやすくなります。
Issue テンプレートの活用
GitHub の Issue テンプレートを活用すると、必要な情報が漏れなく記載された Issue を効率的に作成できます。テンプレートの各セクションの文字数目安を示します。
- バグ報告テンプレート: 合計 300〜600 文字。環境情報、再現手順、期待動作、実際の動作のセクションを含む
- 機能要望テンプレート: 合計 200〜500 文字。背景、提案内容、代替案のセクションを含む
- 質問テンプレート: 合計 100〜300 文字。質問内容、試したこと、関連ドキュメントのセクションを含む
まとめ
GitHub Issue・PR の文字数は、タイトルが 30〜80 文字、本文が 200〜1,000 文字、コミットメッセージが 50〜72 文字 (1 行目) が目安です。再現手順や変更理由を明確に記載することで、チームの開発効率が向上します。Issue や PR の文字数確認には、文字数カウントスをぜひご活用ください。