概要
GitHub Discussionsは、プロジェクトコミュニティがオープンなフォーマットで対話できる協働的コミュニケーションフォーラムである。
Issuesが具体的な作業タスクの追跡を目的とするのに対し、Discussionsは初期段階のアイデア検討、質問への回答、情報共有、コミュニティとの交流を目的とする。
IssuesとDiscussionsの使い分けを以下に示す。
| 機能 | 説明 |
|---|---|
| Issues | バグ報告、機能リクエスト、具体的な作業タスクの追跡に使用する。 スコープが確定した作業を担当者・マイルストーンと紐付けて管理する場合に適している。 |
| Discussions | 初期段階のアイデア検討、コミュニティへの質問、告知、成果物の共有に使用する。 スコープが未確定の段階でコミュニティと議論し、方向性を決めてからIssueに移行する運用が推奨される。 |
Discussionsで議論が進み、具体的な作業として着手することが決まった段階でIssueへ変換できる。
逆に、IssueをDiscussionsに変換することも可能である。
Discussionsの有効化
リポジトリでの有効化
リポジトリオーナー、またはそのリポジトリへの書き込み権限を持つユーザがDiscussionsを有効化できる。
有効化の手順を以下に示す。
- リポジトリのページ上部にある[Settings]タブを選択する。
- [Features]セクションまでスクロールして、[Discussions]の項目を確認する。
- [Set up discussions]ボタンを選択する。
- ウェルカムポストのタイトルと本文を編集する。
- [Start discussion]ボタンを押下して、有効化を完了する。
有効化後、リポジトリのナビゲーションバーに[Discussions]タブが表示される。
組織レベルでのDiscussions
組織オーナーは、組織全体に対してDiscussionsを有効化できる。
有効化の手順を以下に示す。
- 組織のページから[Settings]タブを選択する。
- Discussionsの項目を確認する。
- [Enable]ボタンを押下して有効化する。
- ソースリポジトリを指定する。
組織レベルのDiscussionsでは、ソースリポジトリを指定する必要がある。
Discussionsへの権限は、指定したソースリポジトリの権限設定に基づいて適用される。
カテゴリ
デフォルトカテゴリ
Discussionsを有効化すると、以下に示すデフォルトカテゴリが自動的に作成される。
| カテゴリ名 | 絵文字 | 用途 |
|---|---|---|
| Announcements | 📣 | メンテナーやコントリビュータからの更新情報・告知を投稿する。 |
| General | 🗳️ | プロジェクトに関するオープンエンドな議論を行う。 |
| Ideas | 💡 | 新機能の提案や既存機能の改善アイデアを共有する。 |
| Polls | 🗳 | 投票を実施してコミュニティの意見を収集する。 |
| Q&A | 🙏 | 技術的な質問を投稿して、コミュニティから回答を得る。 |
| Show and tell | 🙌 | プロジェクトを使用して作成した成果物・作品を展示および共有する。 |
カテゴリの形式
各カテゴリには以下に示す4つの形式のいずれかを設定できる。
| 形式 | 説明 |
|---|---|
| Open-ended discussion | 自由な議論形式 回答のマーク機能は使用できない。 GeneralやIdeasに適している。 |
| Question / Answer | 構造化されたQ&A形式 回答のマーク機能が有効になり、有用な回答をハイライト表示できる。 |
| Announcement | メンテナーのみが投稿できる告知形式 コミュニティメンバーはコメントのみ可能 |
| Poll | 投票形式 選択肢を提示してコミュニティの意見を数値で収集する。 |
カスタムカテゴリの管理
maintain権限 または admin権限を持つユーザは、カスタムカテゴリを作成・編集・削除できる。
カスタムカテゴリの仕様を以下に示す。
- カテゴリ名は一意である必要がある。
- 既存のカテゴリ名と重複するカテゴリは作成できない。
- 各カテゴリには名前と絵文字のペアを設定する。
- 絵文字はカテゴリの識別に使用され、一覧表示で視覚的な区別を助ける。
- 1つのリポジトリまたは組織に作成できるカテゴリ数は最大25個である。
- カテゴリのネスト (階層化) が可能である。
- サブカテゴリを作成して、より細かい分類が行える。
カテゴリテンプレート
カテゴリごとにテンプレートを設定できる。
テンプレートを設定すると、そのカテゴリで新規ディスカッションを作成する時に記入すべき情報が事前に表示され、投稿者が必要な情報を漏れなく記載できるよう促す。
テンプレートはYAML構文で記述する。
設定例を以下に示す。
name: Bug Report
description: バグ報告のテンプレート
labels: ["bug"]
body:
- type: markdown
attributes:
value: |
バグ報告ありがとうございます。以下の項目を記入してください。
- type: textarea
id: description
attributes:
label: バグの説明
description: バグの内容を詳しく説明してください。
placeholder: 説明を入力してください。
validations:
required: true
- type: textarea
id: steps
attributes:
label: 再現手順
description: バグを再現する手順を記載してください。
placeholder: "1. ...\n2. ...\n3. ..."
validations:
required: true
ディスカッションの作成と管理
ディスカッションの作成
[Discussions]タブからディスカッションを作成する手順を以下に示す。
- リポジトリ または 組織の[Discussions]タブを選択する。
- [New discussion]ボタンを押下する。
- 投稿するカテゴリを選択する。
- タイトルと本文を入力する。
- [Start discussion]ボタンを押下して投稿する。
本文はMarkdown記法で記述でき、コードブロック・画像・リンクの挿入が可能である。
コメントとリアクション
ディスカッションへのコメントはスレッド化されており、特定のコメントに対して返信することで会話の流れが整理される。
コメントに対してアップボート (👍) を付けることができ、有用なコメントが視覚的に強調されてコミュニティの合意形成を助ける。
絵文字リアクション機能により、コメント・投稿に対して感情を簡単に表現できる。
回答のマーク (Q&A)
Q&A形式のカテゴリでは、ディスカッションの作成者 または triage権限以上を持つユーザが、有用なコメントを回答としてマークできる。
回答としてマークされたコメントはページ上部にハイライト表示され、同様の問題を持つ他のユーザが素早く解決策を見つけられるようになる。
回答がマークされたディスカッションは 回答済み 状態となり、フィルタリングで絞り込むことができる。
ピン留め
書き込み権限を持つユーザは、重要なディスカッションを[Discussions]タブの上部にピン留めできる。
ピン留めしたディスカッションは一覧の最上部に固定表示され、コミュニティメンバーが重要な情報に素早くアクセスできる。
ロック
書き込み権限を持つユーザは、ディスカッションをロックできる。
ロックが適切な場面を以下に示す。
- 不建設的な議論が続いている場合
- コミュニティ規約に違反したコンテンツが含まれている場合
- 解決済みで追加のコメントが不要な場合
ロック中も書き込み権限を持つユーザはコメントを投稿できる。
ロック時にリアクションのみ許可するオプションを選択することも可能である。
Issueへの変換
ディスカッションで議論が進み、具体的な作業として着手することが決まった場合、ディスカッションをIssueに変換できる。
変換の手順を以下に示す。
- ディスカッションページを開く。
- 右側のサイドバーにある[Convert to issue]を選択する。
変換後、ディスカッションのタイトルと本文はIssueに引き継がれる。
変換元のディスカッションにはリンクが表示され、経緯を追跡できる。
逆に、IssueをDiscussionsに変換することも可能である。
Issueの詳細ページのサイドバーから[Convert to discussion]を選択して、変換先のカテゴリを指定する。
カテゴリの変更
書き込み権限を持つユーザは、投稿済みディスカッションのカテゴリを変更できる。
カテゴリを変更することにより、ディスカッションの性質が変わった場合 (例: Generalで始まった議論がQ&A形式に適するようになった場合) に適切なカテゴリへ移動できる。
ディスカッションの転送
書き込み権限を持つユーザは、ディスカッションを別のリポジトリに転送できる。
転送の手順を以下に示す。
- ディスカッションページを開く。
- 右側のサイドバーにある[Transfer this discussion]を選択する。
- 転送先のリポジトリを選択する。
- [Transfer discussion]ボタンを押下して、転送を完了する。
Announcement形式のカテゴリのディスカッションは転送できないことに注意する。
投票 (Polls)
投票の作成
[Polls]カテゴリを選択してディスカッションを作成すると、投票を実施できる。
投票の作成手順を以下に示す。
- [Discussions]タブから[New discussion]を選択する。
- [Polls]カテゴリを選択する。
- 質問文をタイトルに入力する。
- 最低2つの選択肢を入力する。
- 選択肢は必要に応じて追加できる。
- [Start discussion]ボタンを押下して、投票を開始する。
投票結果の確認
投票の結果はリアルタイムで更新され、各選択肢の得票数と得票率がグラフで表示される。
投票はコミュニティの意見収集や、新機能の関心度測定に有効である。
複数選択肢を提示して優先度を把握することにより、開発の方向性決定に活用できる。
ラベル
ディスカッションへのラベル適用
リポジトリに設定されたラベルをディスカッションに適用できる。
ラベルの適用手順を以下に示す。
- ディスカッションページを開く。
- 右側のサイドバーにある[Labels]セクションを選択する。
- 適用するラベルを選択する。
カテゴリとラベルを組み合わせることにより、より細かい分類が可能になる。
例えば、Q&Aカテゴリに対して "help wanted"ラベルを付けることで、回答を必要としているディスカッションを素早く特定できる。
モデレーション
コメント管理
書き込み権限を持つユーザは、以下に示すコメント管理操作を実行できる。
- コメントの非表示
- 不適切なコメントを折りたたんで表示を抑制する。
- 非表示にしたコメントは このコメントは非表示になっています と表示されて、表示する権限を持つユーザは展開して確認できる。
- コメントの編集
- コメント内容を修正する。
- 編集履歴はユーザに表示される。
- コメントの削除
- コメントを完全に削除する。
- 削除後は復元できないため慎重に操作する。
ユーザの制限とブロック
書き込み権限を持つユーザは、特定のユーザをブロックしてリポジトリへのアクセスを制限できる。
ブロックの種類を以下に示す。
- 無期限ブロック
- 解除するまでブロックが継続する。
- 重大な規約違反があった場合に使用する。
- 期間限定ブロック
- 指定した期間 (1日、3日、7日、30日) のみブロックする。
- 一時的な冷却期間を設ける場合に使用する。
期間限定ブロックは指定期間が終了すると自動的に解除される。
モデレータ権限の付与
リポジトリのメンテナーは、アクティブなコントリビュータにtriage権限を付与することにより、モデレータとして活動してもらえる。
トップコントリビュータの判定基準を以下に示す。
- 過去30日間に、Q&Aカテゴリで回答としてマークされたコメント数をもとに算出する。
- 貢献度の高いユーザが自動的にトップコントリビュータとして表示される。
triage権限を付与することにより、そのユーザは以下の操作が行えるようになる。
- Q&Aディスカッションで回答をマークする。
- ディスカッションのカテゴリを変更する。
- ディスカッションをピン留めする。
- ディスカッションをロックする。
コミュニティガイドライン
Discussionsを健全に運営するために、コミュニティガイドラインを設定することが推奨される。
ガイドラインの設定場所としては以下が適している。
- リポジトリの README.md ファイル
- IssueとDiscussionsの使い分けを明記する。
- CONTRIBUTING.md ファイル
- コントリビューションのルールと合わせて、Discussionsの利用ルールを記載する。
- Discussionsのウェルカムポスト
- Discussionsを有効化した時に作成するウェルカムポストにガイドラインを記載する。
検索とフィルタリング
検索方法
Discussionsの検索はタイトル、本文、コメントの内容を対象として実行できる。
検索の手順を以下に示す。
- [Discussions]タブを開く。
- 検索バーにキーワードを入力して、[Enter]キーを押下する。
GitHubの全体検索からもDiscussionsを検索できる。
全体検索では type:discussions フィルタを使用して、Discussionsのみに絞り込むことができる。
# GitHub全体検索でのDiscussions検索例 type:discussions repo:owner/repositoryキーワード
フィルタリングオプション
[Discussions]タブでは、以下に示すフィルタリングオプションを利用できる。
| フィルタ種別 | オプション | 説明 |
|---|---|---|
| カテゴリ | 各カテゴリ名 | 選択したカテゴリのディスカッションのみを表示する。 |
| ステータス | 回答済み (Answered) | Q&Aカテゴリで回答がマークされたディスカッションを表示する。 |
| ステータス | 未回答 (Unanswered) | Q&Aカテゴリで回答がマークされていないディスカッションを表示する。 |
| ソート | 新着順 (Newest) | 作成日時が新しい順にディスカッションを並べる。 |
| ソート | 最近更新 (Recently updated) | 最後にコメントや更新があった順に並べる。 |
| ソート | コメント数 (Most commented) | コメント数が多い順にディスカッションを並べる。 |
推奨事項
Discussionsを効果的に活用するための推奨事項を以下に示す。
- 段階的移行 (DiscussionsからIssueへ)
- 新しいアイデアや要望は最初にDiscussionsに投稿して議論する。
- スコープが確定して、具体的な作業として着手が決まった時点でIssueに変換する。
- この運用により、スコープが不明確なIssueが乱立することを防げる。
- 投票の活用
- 新機能の候補が複数ある場合、Pollsカテゴリで投票を実施してコミュニティの関心度を測定する。
- 数値データとして優先度の判断材料にできる。
- ガイドラインの明記
- README.md または CONTRIBUTING.md でIssueとDiscussionsの使い分けを明記する。
- 新規コントリビュータが適切な場所に投稿できるよう案内することで、メンテナーのトリアージコストを削減できる。
- Q&Aの回答マークを活用する
- 有用な回答には積極的に回答マークを付ける。
- 回答済みのディスカッションが蓄積されることにより、同様の問題を持つユーザが自己解決しやすいナレッジベースが形成される。
- Announcementカテゴリの活用
- リリース情報、重要な変更、メンテナンス情報は、Announcementカテゴリで投稿する。
- メンテナーのみが投稿できる形式であるため、重要情報の信頼性を担保できる。
参考リンク