OSSのCONTRIBUTING.mdは何をどこまで書けばいいのか

OSSリポジトリを公開したものの、CONTRIBUTING.md を「とりあえず置いただけ」で中身が薄い、あるいはそもそも用意していないケースは少なくありません。しかしIssueやPull Requestの質は、コントリビューターがどれだけ迷わず動けるかに大きく左右されます。本記事では、GitHub公式ドキュメントとContributor Covenant 3.0を根拠に、CONTRIBUTING.md に何をどこまで書くべきかを整理します。

CONTRIBUTING.mdの役割

CONTRIBUTING.md は「貢献の仕方」を説明するドキュメントです。README.mdが「このプロジェクトが何をするものか」を説明するのに対し、CONTRIBUTING.mdは「このプロジェクトにどう関わればよいか」を説明するという役割分担になります。

GitHubの公式ガイド¹では、CONTRIBUTING.md閲覧時のリポジトリオーナー側の目的とコントリビューター側の目的を次のように整理しています。

• オーナー側: 有意義なIssueやPull Requestを作成する手順をコミュニティに周知できる
• コントリビューター側: 「上手に構築されたPull Request」を提出するための指針を得られる

つまりCONTRIBUTING.mdは、メンテナが同じ説明を毎回繰り返す手間を減らすためのドキュメントでもあります。

配置場所とGitHub上での見え方

GitHubは CONTRIBUTING.md の配置場所として次の3箇所を認識します¹。

• リポジトリのルートフォルダ
• .github/ フォルダ
• docs/ フォルダ

複数の場所に同名ファイルが存在する場合、GitHubは .github → ルートフォルダ → docs の優先順で1つだけを採用します。

個人的には .github/CONTRIBUTING.md に置くのがおすすめです。ルートディレクトリの一覧をREADMEやライセンスファイルだけに保ち、プロジェクト運用系のファイル（Issueテンプレート、PRテンプレート、ワークフローなど）を .github/ にまとめられるためです。

正しく配置すると、GitHub上では以下のタイミングで自動的にリンクが表示されます。

• Issue作成画面
• Pull Request作成画面
• リポジトリの「コミュニティ」タブ（インサイト配下）
• README横のサイドバーにある「Contributing」リンク

つまりCONTRIBUTING.mdは、README.md内から手動でリンクを張らなくても、GitHubのUIが自動的に導線を作ってくれるファイルなのです。

何を書くべきか

GitHub公式ガイドが推奨する内容は、大きく3つに分類できます¹。

1. コントリビュートの手順: Issueの立て方、Pull Requestの作成手順、レビューの流れ
2. 参考資料へのリンク: 開発環境のセットアップ手順、外部ドキュメント、行動規範（Code of Conduct）
3. 期待値の明示: コミュニティやコントリビューターの行動に対して何を期待するか

これを実務的なテンプレートに落とし込むと、次のような構成になります。

.github/CONTRIBUTING.md

## Contributing

このプロジェクトへの貢献に興味を持っていただきありがとうございます。

### 行動規範

このプロジェクトは [Code of Conduct](./CODE_OF_CONDUCT.md) を採用しています。
参加にあたっては内容に同意したものとみなします。

### バグ報告・機能要望

Issueを立てる前に、既存のIssueで同様の報告がないか検索してください。
バグ報告には以下を含めてください。

- 再現手順
- 期待した動作と実際の動作
- 環境情報（OS、バージョンなど）

### 開発環境のセットアップ

\`\`\`bash
git clone https://github.com/<org>/<repo>.git
cd <repo>
npm install
npm test
\`\`\`

### Pull Requestの作成手順

1. Issueで対応方針について合意を取る（小さな修正は不要）
2. `main` からブランチを切る
3. 変更に対応するテストを追加する
4. `npm test` と `npm run lint` が通ることを確認する
5. Pull Requestを作成し、関連するIssueをリンクする

### コミットメッセージの規約

（採用している場合のみ）Conventional Commits に従ってください。

### レビューについて

レビューには通常◯日以内に対応します。

ポイントは、「これを埋めれば動く」という具体性です。抽象的な精神論だけを書いても、コントリビューターは実際にどうコマンドを打てばよいのか分かりません。特に「開発環境のセットアップ」と「テストの実行方法」は、実際にコピー&ペーストで動くコマンドとして書くべきです。

プロジェクトの規模が小さいうちは、CONTRIBUTING.mdを数行の簡潔なものにしておいても構いません。無理に立派なテンプレートを埋めようとして、実態と乖離した記述をするほうが有害です。

行動規範（Code of Conduct）との関係

CONTRIBUTING.mdが「どうコントリビュートするか」の技術的な手順書であるのに対し、CODE_OF_CONDUCT.md は「コミュニティ内でどう振る舞うか」を定める文書です。両者は役割が異なるため別ファイルに分け、CONTRIBUTING.mdから明示的にリンクするのが一般的です。

行動規範をゼロから書き起こす必要はありません。事実上の業界標準になっているのが Contributor Covenant です。2026年8月時点の最新版はバージョン3.0で、CC BY-SA 4.0ライセンスの下、自由に改変・再配布できます。

Contributor Covenant 3.0の構成は次の7セクションです²。

セクション	内容
私たちの誓い	包括的で安全なコミュニティを構築するという宣言
望ましい行動	尊重・親切・責任など7項目の共通価値観
制限される行動	ハラスメント・人格攻撃・差別など7種類の禁止事項
その他の制限	身元詐称、出典未記載、宣伝活動などの規制
問題の報告	違反を報告する手段と、報告後の対応方針
問題への対処と修復	注意 → 一時制限 → 停止 → 永久追放という段階的な対応基準
適用範囲	プロジェクトが関わるすべての場（Issue、PR、チャット、オフラインイベント等）に適用されることの明記

導入時に必ずカスタマイズが必要なのは「問題の報告」セクションです。テンプレートには報告先が [※ 報告先をここに記入してください] のようなプレースホルダーになっている箇所があるため、実際の連絡先（メールアドレスやフォームのURL）に差し替える必要があります。個人プロジェクトであっても、放置せず自分の連絡先を明記しておくべきです。

導入手順は以下の通りです。

1. Contributor Covenant公式サイトからテキストを取得する
2. CODE_OF_CONDUCT.md としてリポジトリのルートに配置する
3. 報告先などのプレースホルダーを実際の値に置き換える
4. README.mdとCONTRIBUTING.mdの両方からリンクを張る

CONTRIBUTING.mdに行動規範を全文埋め込むこともできますが、分けておくメリットが2つあります。

• GitHubは CODE_OF_CONDUCT.md というファイル名を認識すると、リポジトリの「コミュニティ」タブやIssueテンプレートに専用の導線を自動生成します
• 行動規範はライセンス（CC BY-SA 4.0）に基づくテキストなので、独立したファイルにしておくと出典や改変範囲を管理しやすくなります

よくある落とし穴

• 手順が実態と乖離している: npm test と書いてあるのに実際は pnpm test が必要、といった食い違いはコントリビューターの離脱に直結します。READMEやCIの設定ファイルと内容を一致させる運用が必要です。
• 報告先が空欄のまま: Contributor Covenantのテンプレートをそのまま貼り付け、報告先のプレースホルダーを埋め忘れるケースはよく見かけます。行動規範があっても報告先が不明では機能しません。
• 抽象的な精神論に終始する: 「良いコントリビューションをお待ちしています」だけでは、実際に何をすればいいか分かりません。具体的なコマンドや手順に落とし込むことが重要です。
• リポジトリごとの配置ゆらぎ: 複数リポジトリを運用している組織で、あるリポジトリはルート、別のリポジトリは .github/ に置いているといった不統一があると、優先順位のルール¹により意図しないファイルが表示されることがあります。組織内でテンプレートを揃えておくと安全です。

まとめ

CONTRIBUTING.md は、GitHubのUIが自動的に導線を作ってくれる分、書いておくだけで効果が出やすいドキュメントです。最低限、「コントリビュート手順（Issue・PRの作法）」「開発環境のセットアップ」「行動規範へのリンク」の3点を、実際にコピー&ペーストで動く粒度で書いておくことをおすすめします。行動規範はContributor Covenantをベースにすれば、ゼロから文言を練る必要はありません。プロジェクトの規模に応じて過不足なく整備し、実態との乖離が生まれないよう更新し続けることが、結果的にコントリビューターにとって一番親切な状態です。

参考リンク

1. リポジトリのコントリビューターのためのガイドラインの設定 - GitHub Docs ↩ ↩² ↩³ ↩⁴

2. Contributor Covenant 行動規範 バージョン3.0 (日本語版) ↩