貢献する方法

私たちは、明確に提出していただける方であれば、どなたからでもコード、ドキュメント、バグ報告、フィードバックを受け付けています。このページでは、変更を取り込む方法、レビューで何を確認するか、PRを開いた後に何が起こるかといった、実際の手順について説明します。

コード以外の貢献（問題の報告、フィードバック、ヘルプの取得など）については、コミュニケーション を参照してください。

実装前に設計の議論が必要な大きな変更については、RFC プロセス を参照してください。

始める前に

タイプミス以外の修正の場合:

1. 問題トラッカーを確認してください。 すでに誰かが対応しているか、関連する議論が起きている可能性があります。
2. AGENTS.mdを読んでください。 リポジトリのルートには、コンパクトで常時読み込まれるコントラクトが含まれています。詳細なリスク、安定性、信頼できる情報源、スキル発見のリファレンスにはCoding agent guidelinesを使用してください。
3. アーキテクチャ、設定、セキュリティ、ワークフロー、ガバナンス、CI、リリース動作、またはAI支援によるコントリビューションポリシーに関わるあらゆる事柄については、アーキテクチャとコントリビューションマップを使用してください。
4. ブランチを選択してください。 PR は master をターゲットにします。リポジトリをフォークし、そこからブランチを作成してください。develop や integration などのブランチを経由する必要はありません。

フロー

fork → branch → commit → push → open PR → review → merge (squash)

主要なチェックポイント:

• PR テンプレート: .github/pull_request_template.md。記入してください。概要、テストの証拠、互換性のセクションは必須です。
• CI: すべてのPRで実行されます。ci.yml は統合ゲートであり、すべてのレッグが成功する必要があります。
• ラベル: メンテナーはラベルを使ってレビューの深さを振り分けます。PRを作成する前にすべてのラベルファミリーを把握しておく必要はありません。ラベルが明らかに間違っているように見えて、自分で編集できない場合は、その不一致をコメントで指摘してください。ラベル権限を持つメンテナーやレビュアーが明らかな不一致を直接修正できます。
• レビュールーティング: スコープ、関連する課題、検証、リスク/ロールバックのコンテキストを十分に明確にして、レビュアーが適切なレビューパスを素早く選択できるようにします。
• レビュー: メンテナーがレビューします。指摘事項にはPRレビューの分類体系を使用します: 🔴 ブロッカー、🟡 警告、🔵 提案、🟢 称賛、✅ 解決済み。ブロッカーには対応してください。警告には返答が必要です。提案は任意です。

コードスタイル

• cargo fmt でクリーン（CI でチェック済み）
• cargo clippy -D warnings のクリーン（CI でチェック済み）
• 未使用のプロダクションコードを残さない: 削除するか、動作に組み込むか、フォローアップの課題として追跡してください。アンダースコアのプレフィックスや #[allow(dead_code)] で隠さないでください。アンダースコア付きの名前は、必須だが意図的に未使用とする API、トレイト、コールバックのパラメータに限って使用してください。
• エラー処理: バイナリ境界では anyhow::Result、ライブラリクレートでは型付きエラーを使用します。本番コードパスでは unwrap() / expect() を使用しないでください。? で伝播するか、パニックが起こり得ないことを保証する不変条件を文書化してください。
• 最小限の依存関係: すべての依存はバイナリサイズを増加させる。追加する前にトレードオフを検討すること
• トレイトファースト: zeroclaw-api でトレイトを定義し、適切なエッジクレートで実装する
• デフォルトでセキュア: ブロックリストではなく許可リスト。新しい外部サーフェスはデフォルトでクローズ
• インラインの単体テスト: ファイルの末尾にある #[cfg(test)] mod tests {} または隣接する tests.rs
• シークレット、個人データ、実在ユーザーの識別情報をコミットしないでください。プライバシーとPIIの規律のページがマージゲートとなります

コメントとドリフト

コメントは、長期的な意図、不変条件、危険性、またはソースの所有権を説明するものであるべきです。近くにある制御フローを言い換えたり、スキーマや設定フィールドの一覧を重複させたり、列挙型のバリアントを列挙したり、コードやテストで強制されていない実行時の動作を説明したりするコメントは追加しないでください。そうしたコメントは乖離の温床となり、ソースが変更された後も、将来のコントリビューターやツールがその記述を信頼してしまう可能性があります。

コメントで他の場所が管理する動作に言及する必要がある場合は、内容を複製するのではなく、その管理元を示してください。あるブランチがなぜ安全なのか、どの契約がルールを管理しているのか、あるいはどのソースを最初に変更すべきかを説明するコメントを優先してください。

推奨:

• 設定スキーマが受け入れるエイリアスを管理します。このリゾルバは汎用のままにしてください。
• このパニックには到達できません。パーサーがそれより前に空のツール名を拒否するためです。

回避:

• サポートされているバリアントは A、B、C です。
• このフラグは常にベクトル検索を有効にします。

コード、設定、WIT、スキーマ、テストが変更されるたびにコメントを手動で編集しなければ記述の正しさを保てない場合は、代わりにソースを明確にするか、ソースへの参照を追加してください。

テスト

• コードと同一の場所にあるユニットテスト（mod tests）
• tests/ 内の統合テストとクレートローカルの単体テスト: cargo nextest run --locked --workspace --exclude zeroclaw-desktop で実行します
• 機能ゲート付きのコードには、機能ゲート付きのテストが必要です。
• スキーマやSQLを検証するテストではデータベースをモック化しないでください。統合テストは実際のSQLiteを使用する必要があります

完全な5段階の階層構造（ユニット / コンポーネント / インテグレーション / システム / リブ）、共有モックインフラストラクチャ、およびJSONトレックスフィクスチャフォーマットについては、テストをご覧ください。

ドキュメントの変更

• プロースの変更は docs/book/src/**/*.md (この mdBook) に追加してください。
• Rustdoc (/ /) の変更は、デプロイ時に API リファレンスを自動的に更新します。
• リファレンスページ（docs/book/src/reference/cli.md、config.md）は無視対象の生成物です。手動で編集したり、コミットしたりしないでください。所有元の CLI/config ソースからの変更をプレビューするには、cargo mdbook refs を実行してください。
• ローカライズ: 英語の Markdown が信頼できる唯一の情報源です。通常の英語ドキュメントの PR では、広範囲にわたって生成される .po の変更を省略することがあります。Building the docs locally にある標準の PR 本文の注記を使用してください。
• 翻訳キャッシュの PR、リリース翻訳パス、新しいロケールでは cargo mdbook sync を実行し、生成された .po ファイルをコミットして、cargo mdbook check で検証してください

ブログまたはウェブサイトのメタデータを公開する

ブログ記事を公開する場合や、その他の方法で公開ブログのメタデータを更新する場合は、同じPR内で手動管理しているフィードのタイムスタンプも更新してください:

• web/public/blog/rss.xml: <lastBuildDate> を RFC 2822 / GMT 形式で最新の投稿公開時刻に設定します
• web/public/blog/atom.xml: <updated> を ISO 8601 UTC 形式で最新の投稿公開時刻に設定する
• web/public/sitemap.xml: /blog エントリの <lastmod> を最新の公開日に設定します

フィード検出をローカル環境に限定する:

• web/index.html では /blog/rss.xml、/blog/atom.xml、/sitemap.xml をルート相対リンクのまま維持する必要があります
• web/public/sitemap.xml には XML フィードファイルではなく、ユーザー向けの /blog ページを記載する必要があります

コミットメッセージ

Conventional Commits:

feat(providers): add support for DeepSeek reasoning mode
fix(channels/matrix): prevent duplicate device sessions after verify
docs(getting-started): add YOLO-mode quick-start
refactor(runtime): split agent loop into steps
chore: bump tokio to 1.43

AIによる支援を伴う共同作業は歓迎しますが、PR本文やコミットメッセージの末尾にbot/AIのattribution trailerや生成ツールのfooterを追加しないでください。人間によるCo-authored-by:のtrailerは、優先ルールおよびプライバシールールに従う場合、取り込んだコントリビューターの作業に対して引き続き適切です。完全な規範についてはFND-005（Contribution Culture）を参照してください。

プルリクエスト

タイトルはsquashコミットを反映しています：

feat(scope): short description

本文は PR テンプレートを使用します。テストセクションは必須です：変更の確認方法を説明し、変更に一致するチェックを貼り付けてください。How you can test の下にあるレビュアー実行の A/B レシピは、手動検証が有用なシグナルを追加する場合にのみ必要です。ドキュメントのみ、純粋なリファクタリング、または意味のあるレビュアーテストパスがない軽微な変更の場合は N/A と記入してください。ドキュメントのみの PR では、scripts/ci/docs_quality_gate.sh と scripts/ci/docs_links_gate.sh を使用するか、リンクチェックで検査する追加リンクがなかった理由を説明してください。Rust/コードの PR では、変更されたサーフェスに一致する証拠を使用してください：必須の CI チェック、焦点を絞った crate または回帰テスト、手動スモーク、または狭い証拠では見逃すものを広範なカバレッジが証明する場合のフルワークスペースチェック。必須の CI が変更されたサーフェスをカバーしている場合、最新の必須 CI で十分です。同じ head、ターゲット、フィーチャーセットを単に複製するために追加のローカル Cargo は不要です。PR が既知の CI カバレッジギャップに依存する場合は、さらに証拠を追加してください：プラットフォーム固有のテスト、クロスプラットフォーム lint、デスクトップアプリのカバレッジ、リリースターゲットビルド、古い CI、または利用できない CI。「自分のマシンでは動く」は証拠ではありません。

リスクラベルは、変更の大まかな分類ではなく、実際の変更内容とその影響を表します。メンテナーのラベルガイドに従ってください: risk:low は、本番環境、互換性、ビルド、リリース、ガバナンスに影響を与えないドキュメント、フィクスチャ、または機械的なメタデータを示します。risk:medium は通常の動作変更を示し、risk:high は具体的な信頼、認証情報、互換性、ガバナンス、またはリリース権限の境界を示します。domain:security は risk:* とは独立しており、実効性のあるセキュリティ境界を示します。

risk:high または domain:security のいずれかが付いたPRには、綿密なレビュー、変更に見合ったロールバック計画、そしてマージ前に独立したCore Team承認2件が必要です。maintainerが今後の自動的なリスク置換を凍結する必要がある場合は risk:manual を使用してください。これによってレビュー要件を緩和することはできません。

PR の後

マージ戦略: スカッシュマージを使用し、完全なコミット履歴を本文に保持します。正確なフォーマットについては .claude/skills/squash-merge/SKILL.md を参照してください。TL;DR: 件名には PR タイトル + (#number)、本文には元のコミットの箇条書きリストを記載します。

リリース: 変更は master ブランチにマージされますが、master ブランチからは自動でリリースされません。リリースが完了すると、メンテナーがバージョン番号を bump し、vX.Y.Z というタグを付けます。CHANGELOG にあなたの PR が反映されます。

支援が必要な領域

行動規範

いやな態度を取らないでください。意見には反対しても、人を否定してはいけません。メンテナーが自分で管理したくないものをクローズすることは受け入れてください。通常は説明が添えられますが、時には説明がないこともあります。クローズが不当だと感じたら、質問してください。質問しても進展がなければ、次に進みましょう。

関連項目も参照してください

• RFC プロセス: パッチより大きな変更すべてに対して
• アーキテクチャと貢献マップ: 最初に読むべきアーキテクチャ、基盤、ワークフローのドキュメント
• コミュニケーション: チームへの連絡方法
• メンテナー → 概要: メンテナーが日々行うこと