コミュニティヘルスファイルで参加障壁を下げる

リポジトリ作った、Projectも設定した、次は？「参加の仕方が分からない」で離脱されないために、ドキュメントを整備します。
今回はコミュニティヘルスファイルの3点セット（CONTRIBUTING・CODE_OF_CONDUCT・SECURITY）を、wagtail-reusable-blocksでどう設計したかを振り返ります。

KEY TAKEAWAYS

この記事でわかること

コントリビューターが迷わないドキュメント設計
3つのファイルの役割分担と書くべき内容
OSSでも企業でも使える、オンボーディングコスト削減術

用語の定義

TERM 01

Community Health Files

GitHubがプロジェクトの健全性を評価するために推奨する標準ファイル群。CONTRIBUTING・CODE_OF_CONDUCT・SECURITYなど。

TERM 02

CONTRIBUTING.md

コントリビューター向けガイド。開発環境のセットアップ、コーディング規約、テスト方法、ブランチ戦略などを記載。

TERM 03

CODE_OF_CONDUCT.md

行動規範。コミュニティ内での許容される/許容されない行動を明文化。ハラスメント防止とインクルーシブな環境作りのため。

TERM 04

SECURITY.md

セキュリティポリシー。脆弱性の報告方法、サポートバージョン、対応タイムラインを記載。公開Issueでの報告を防ぐ。

なぜコミュニティヘルスファイルが必要？

前回までで、リポジトリとProject Boardは作りました。でも「どうやって参加すればいいの？」が分からないと、誰も手伝ってくれません。

実はこれ、OSSだけの話じゃなく、企業の社内プロジェクトでも全く同じなんです。

問題1

「開発環境どう作るの？」→ 聞くの面倒、離脱

問題2

「コーディング規約は？」→ レビューで怒られる、嫌になる

問題3

「セキュリティバグ見つけた！」→ 公開Issue、大惨事

解決策: コミュニティヘルスファイルで「参加の仕方」を事前に明文化すれば、この3つ全部解決します。

wagtail-reusable-blocksでは初日にREADMEと一緒に整備。結果、「どうすればいい？」の質問ゼロで開発に集中できました。

ステップ1: CONTRIBUTING.md作成

一番重要なファイル。「このプロジェクトに参加するための全手順」を書きます。

何を書くべきか

必須セクション

wagtail-reusable-blocksでは、コントリビューターが迷わないように以下を明記しました。

セクション	内容	なぜ必要か
Development Setup	・Prerequisites ・Clone & Setup ・Running Tests	環境構築で挫折させない
Coding Standards	・Formatter/Linter (Ruff) ・Naming conventions ・Type annotations	レビューで揉めない
Testing Standards	・Test structure ・Coverage target ・Fixtures	品質を保つ
Branch Strategy	・Git Flow ・Branch naming ・Protected branches	どこにPR出せばいいか分かる
Workflow	・Issue確認 → Branch作成・コミット → PR作成・Release process	手順が明確

書きすぎ？いや、ちょうどいい

wagtail-reusable-blocksのCONTRIBUTING.mdは423行あります。長い？

短すぎるCONTRIBUTING.mdの問題

「PRください」だけ → どうやって？
「テスト書いて」だけ → どこに？どう書く？
「コーディング規約守って」だけ → 何を？
→ 結局、Slackで質問、DM、時間の無駄

詳しく書く = オンボーディングコスト削減

長いCONTRIBUTING.mdは「質問する時間 < 読む時間」になった瞬間に価値が出ます。2人目以降の参加者から、すでにペイします。

実装: wagtail-reusable-blocksの構成

実際のファイル構成です。Mermaid図でブランチ戦略も可視化しました。

ポイント:

セットアップコマンドはコピペで動く
コーディング規約は表形式で一目瞭然
テスト例は実際のコード付き
ブランチ戦略はMermaid図で説明

実例:CONTRIBUTING.md - 423行の詳細ガイド

Markdown

# Contributing to wagtail-reusable-blocks

## Development Setup

### Prerequisites
- Python 3.10+
- uv (recommended) or pip

### Clone and Setup
```bash
git clone https://github.com/...
uv pip install -e ".[dev]"
```

## Coding Standards
| Item | Standard |
|------|----------|
| Formatter | Ruff |
| Line length | 88 |

## Branch Strategy
```mermaid
gitGraph
commit id: "initial"
branch develop
...
```

## Workflow
1. Check existing issues
2. Create branch
3. Make changes
4. Push and create PR

ステップ2: CODE_OF_CONDUCT.md作成

行動規範。「このコミュニティで何が許されて、何が許されないか」を明文化します。

なぜ必要か

「うちは小規模だから不要」は間違い

wagtail-reusable-blocksはソロ開発ですが、CODE_OF_CONDUCTを最初から設置しました。

なぜ最初から？

後から追加しにくい → 既存メンバーに「なんで今更？」と思われる
GitHubが推奨 → Community profileで評価される
コントリビューター獲得 → 「安全なプロジェクト」の証明
予防措置 → トラブル起きてからじゃ遅い

Contributor Covenant 2.0を採用

一から書かず、業界標準のContributor Covenantをそのまま採用しました。

選択肢	メリット	判断
Contributor Covenant	・業界標準・多言語対応・信頼性が高い	採用
独自作成	・カスタマイズ自由	不採用（法的リスク）
設置しない	・手間なし	不採用（信頼性低下）

Contributor Covenantとは

Kubernetes、Rails、Swift、Rustなど主要OSSプロジェクトの90%以上が採用する標準行動規範。車輪の再発明せず、これ使えばOK。

実装: 3ステップで完了

方法1: GitHub UIで追加（超簡単）

リポジトリ → Insights → Community Standards
「Add」ボタン → Code of conduct
「Contributor Covenant」選択 → Commit
→ 完了！（3クリック）

方法2: 手動でファイル作成

テンプレートをコピーして、報告先だけ自分のプロジェクトに変更。

変更箇所: Enforcementセクションの報告先URLだけ。

Bash

# テンプレート取得
curl https://www.contributor-covenant.org/version/2/0/code_of_conduct.txt \
> CODE_OF_CONDUCT.md

# 報告先を編集
# Enforcement セクションの
# [INSERT CONTACT METHOD] を
# GitHub Issues または Discussions に変更

git add CODE_OF_CONDUCT.md
git commit -m "docs: add code of conduct"

実例:CODE_OF_CONDUCT.md - Contributor Covenant 2.0そのまま

ステップ3: SECURITY.md作成

セキュリティポリシー。「脆弱性見つけたらどうすればいいか」を事前に明示します。

なぜ必要か

「公開Issueで脆弱性報告」を防ぐ

SECURITY.mdがないと、善意のユーザーが公開Issueでセキュリティバグを報告してしまいます。

最悪のシナリオ

ユーザーがSQLインジェクションを発見
「どこに報告すればいいか分からない」→ 公開Issue作成
攻撃者がIssueを発見 → エクスプロイト作成
修正前に悪用される
→ プロジェクトの信頼性崩壊

SECURITY.mdがあれば

「Please do NOT report security vulnerabilities through public GitHub issues.」と明記されてるので、公開報告を防げます。報告先も明確（GitHub Security Advisories）。

必須セクション

セクション	内容	目的
Supported Versions	サポート中のバージョン一覧	どのバージョンで修正されるか明示
Reporting	・報告方法・報告先（Security Advisories）・含めるべき情報	公開Issueを避ける
Response Timeline	・初回応答: 48時間以内・ステータス更新: 7日以内・修正目標: 30日以内	報告者の不安を解消
Disclosure Policy	・修正後に公開・クレジット表記	責任ある開示を促す

Response Timelineが超重要

「報告したけど何も返事がない...」で報告者が痺れを切らして公開、というパターンを防ぎます。48時間以内に初回返信を約束すれば、待ってもらえます。

実装: GitHub Security Advisories活用

GitHub Security Advisoriesを使えば、非公開で脆弱性を報告・管理できます。

手順:

Security tab有効化
Private vulnerability reportingを有効化
SECURITY.mdに報告先を記載
報告があったら通知が来る

実例:SECURITY.md - 62行のポリシー

Markdown

# Security Policy

## Supported Versions
| Version | Supported |
| ------- | --------- |
| 0.x.x   | ✅ |

## Reporting a Vulnerability

**Please do NOT report security
vulnerabilities through public
GitHub issues.**

### How to Report
1. Go to Security tab
2. Click "Report a vulnerability"
3. Fill out the form

### Response Timeline
- Initial Response: Within 48 hours
- Status Update: Within 7 days
- Resolution Target: Within 30 days

### Disclosure Policy
- We will confirm the vulnerability
- We will release a fix
- We will publicly disclose
once a fix is available

企業プロジェクトでも同じことが起きる

コミュニティヘルスファイルはOSSだけの話じゃありません。社内プロジェクトでも、新規参入者向けのドキュメントは必須です。

社内版コミュニティヘルスファイル

ファイル	OSS	企業プロジェクト
CONTRIBUTING.md	コントリビューターガイド	新規参画者向けオンボーディングドキュメント
CODE_OF_CONDUCT.md	コミュニティ行動規範	チームコラボレーションガイドライン
SECURITY.md	脆弱性報告ガイド	セキュリティインシデント報告フロー

よくある問題

ドキュメントがない企業プロジェクト

新人: 「開発環境どう作るの？」→ 先輩に聞く → 先輩の時間を奪う
異動者: 「コーディング規約は？」→ レビューで指摘 → 修正の手戻り
派遣: 「このバグ、セキュリティ的にやばくない？」→ Slackで聞く → 誰も答えない
→ オンボーディングコストが毎回発生

解決策: 最初から書く

トピック#2で言った「ツール分散の罠」と同じ。ドキュメントをサボると、新規参入者が「どこ見ればいい？」で迷子になります。READMEにリンク貼るだけで、オンボーディング時間が1/10になります。

#3 コミュニティヘルスファイルで参加障壁を下げる - Python OSS開発記録

karrinn

目次

この記事でわかること

用語の定義

Community Health Files

CONTRIBUTING.md

CODE_OF_CONDUCT.md

SECURITY.md

なぜコミュニティヘルスファイルが必要？

ステップ1: CONTRIBUTING.md作成

何を書くべきか

必須セクション

書きすぎ？いや、ちょうどいい

実装: wagtail-reusable-blocksの構成

ステップ2: CODE_OF_CONDUCT.md作成

なぜ必要か

「うちは小規模だから不要」は間違い

Contributor Covenant 2.0を採用

実装: 3ステップで完了

方法1: GitHub UIで追加（超簡単）

方法2: 手動でファイル作成

ステップ3: SECURITY.md作成

なぜ必要か

「公開Issueで脆弱性報告」を防ぐ

必須セクション

実装: GitHub Security Advisories活用

企業プロジェクトでも同じことが起きる

社内版コミュニティヘルスファイル

よくある問題

こちらの記事もおすすめ

前の記事

次の記事

参考リンク

プロジェクト関連

公式ドキュメント

参考事例

関連トピック

記事をシェア

karrinn

コメント (0)

コメントを投稿

検索

最近の投稿

#4 Git Flowブランチ戦略でチームの混乱を防ぐ - Python OSS開発記録

#2 GitHub ProjectとMilestonesでロードマップ設計 - Python OSS開発記録

#1 OSSプロジェクト立ち上げ初日の4つの設定 - PythonOSS開発記録

【GitHubActions × Claude】完全自立開発サイクルを実現する

Pythonプロジェクトの長期運用で本当に必要なこと - 環境・品質・型の3本柱

カテゴリー