貢献する方法

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

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

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

始める前に

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

問題トラッカーを確認してください。 すでに誰かが対応しているか、関連する議論が起きている可能性があります。
AGENTS.mdを読んでください。 リポジトリのルートには、コンパクトで常時読み込まれるコントラクトが含まれています。詳細なリスク、安定性、信頼できる情報源、スキル発見のリファレンスにはCoding agent guidelinesを使用してください。
アーキテクチャ、設定、セキュリティ、ワークフロー、ガバナンス、CI、リリース動作、またはAI支援によるコントリビューションポリシーに関わるあらゆる事柄については、アーキテクチャとコントリビューションマップを使用してください。
ブランチを選択してください。 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 が通っていれば、それで十分です。同じ head、target、feature セットを重複して確認するためだけに、追加でローカルの Cargo を実行する必要はありません。

ＣＩのカバレッジに既知のギャップがあるPRが依存している場合は、より多くの証拠を追加してください：プラットフォーム固有のテスト、クロスプラットフォームのlint、デスクトップアプリのカバレッジ、リリースターゲットのビルド、ベースドリフトのみのレビューケースを超えた古いCI、または利用不可のCI。「自分のマシンでは動く」は証拠になりません。

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

A PR に risk:high または domain:security が付いている場合、デフォルトで詳細なレビュー、変更内容に合わせたロールバック計画、そして Core Team による2名の独立した承認が必要です。必須の2人目の Core レビューが、対象となる5営業日の期間内に回答されないままの場合、メンテナーは限定的なexpedited second-review laneを検討できます。適格性と責任に関するすべての条件は、その正式なページで定められています。将来の自動リスク置換をメンテナーが凍結する必要がある場合は risk:manual を使用します。このラベル自体はレビュー要件を下げるものではありません。

PR の後

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

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

支援が必要な領域

領域	どこから始めるか
新しいチャンネル	`crates/zeroclaw-channels/`: 形状が似ている既存のチャネルをコピーします
新しいプロバイダー	`crates/zeroclaw-providers/`: `compatible.rs` はほとんどの OpenAI 互換のものをカバーしています
ドキュメント	`docs/book/src/`: 古くなった、または不足しているとマークされたすべての内容
翻訳	`cargo fluent fill --locale <code>`：メンテナー → ドキュメントと翻訳を参照してください
ハードウェア	`crates/zeroclaw-hardware/`: 新しいボードサポート、新しいセンサードライバー

行動規範

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

ZeroClaw Docs