コントリビューション

Ankole にコントリビュートするということは、最初の編集の前に 2 つのドキュメントを読み、それらが定義する道筋に従うことを意味します。このページは地図です: 権威あるソースを指し示し、それらを通る道筋を名付け、どちらも複製しません。このページとソースドキュメントが矛盾する場合、ソースドキュメントが正しいです。

決定的な性質を先に述べます: Ankole のコントリビューションルールは任意の慣習ではありません。プロジェクトのレビュープロセスと、すべてのコミットをゲートする changelog ルールによって強制されます。AGENTS.md や CONTRIBUTING.md を飛ばしたコントリビューションは、読みに戻るよう求められます。先に読んでください。

ルールを所有する 2 つのドキュメント

AGENTS.md — プロジェクト全体のルール: スコープと権限、changelog をバージョン単位とするルール、コア規律（最小の正しい変更、worse-is-better）、設計優先順位（シンプルさ > 正しさ > 一貫性 > 完全性）、目的忠実性、サブシステム境界。変更をどう行うかを決めるドキュメントです。
CONTRIBUTING.md — コントリビューションの道筋: 6 ステップのローカルセットアップ、Feishu のエンドツーエンド受入、トラブルシューティングの順序、リポジトリマップ、品質ゲート、changelog と PR の手順。変更を何をして着地させるかを決めるドキュメントです。

どちらも自分の領域の真実のソースです。このガイドと残りのドキュメントはそれらにリンクします。ここにあるものはどれもそれらを上書きしません。

セットアップの道筋（6 ステップ）

CONTRIBUTING.md はセットアップを 6 ステップで説明しており、それが権威あるバージョンです。形は次のとおりなので、何に足を踏み入れるかわかります:

リポジトリを取得し、環境を選ぶ — クローンし、macOS/Linux/WSL2 または GitHub Codespaces を選びます。
システムツールをインストールして検証する — bash tools/devkit/scripts/env-setup.sh を実行し、bun、elixir、rustc、cargo clippy、docker がすべて動くことを確認します。各 kit コマンドの内容は kit CLI reference を参照してください。
依存関係をインストールし、PostgreSQL を初期化する — bun install、bun run services:start、bun run control-plane:setup。
完全な開発環境を起動する — bun dev。
初回の製品セットアップを完了する — 有効化し、Feishu テストアプリを作成し、OIDC を設定し、Console でランタイムを設定します。
エンドツーエンドの経路を証明する — 実際の Feishu メッセージが agent に届き、期待した返信が返ることを確認します。

セットアップはページが開いたときには完了していません。実際のメッセージが往復したときに完了します。短い経路は Quick start を、完全な受入は CONTRIBUTING.md を参照してください。

変更の仕方

最初の編集の前に AGENTS.md を読んでください。最も頻繁に出てくるルール:

スコープと権限。 回答や計画を求めるリクエストは読み取り専用の調査を許可します。実装を求めるリクエストは編集を許可します。承認なしにスコープを広げないでください。
changelog はバージョン単位です。 すべてのコミットは正確に 1 つの CHANGELOG.md バージョンを追加し、そのバージョンはコミット内の保持されたすべての変更を記述します。1 つのバージョンが複数のコミットにまたがりません。1 つのコミットが複数のバージョンを含みません。下のセクションを参照してください。
最小の正しい変更。 選択した方向に従い、システムが維持できる契約を守り、理解可能なままの最小の変更を選びます。複雑さを増す抽象化よりも、少しの重複が優れています。
Worse is better。 シンプルさはインターフェースの均一性や理論的完全性に勝ります。シンプルさが勝つときは、契約を狭めるか、サポートしないケースを明示的に拒否し、黙って間違った結果を作らないでください。
目的忠実性。 依頼されたタスクを、より安い代替ではなく実行します。緑のテストは目標ではありません。所有する抽象化を通る実際の経路が目標です。
サブシステム境界。 PostgreSQL は永続的な事実を所有し、Elixir コントロールプレーンは永続状態と監督を所有し、Rust カーネルは共有ネイティブプリミティブを所有し、Bun Agent Computer Worker は実行を所有します。境界をまたぐ変更は、ごまかすのではなく境界を尊重するべきです。

changelog ルール

これはすべてのコミットをゲートするルールであり、最初の試行で多くのコントリビューションが間違えるものです。AGENTS.md から:

すべてのコミットは正確に 1 つのルート CHANGELOG.md バージョンを追加します。
そのバージョンはコミット内のすべての保持されたソース、テスト、ドキュメント、設定、スキーマ、マイグレーション、マニフェスト、ロックファイル、必須の生成ファイル変更を記述します。
1 つのバージョンが複数のコミットにまたがってはならず、1 つのコミットが複数のバージョンを含んではなりません。
バージョンは先頭ゼロなしの MAJOR.MINOR.PATCH を使います。既定では PATCH を上げます。そのコミットによってユーザーまたは運用者が以前はできなかったことをできるようになる場合、あるいは既存の動作が壊れて設定・保存データ・外部の呼び出し側を人が変更しなければならない場合にだけ、MINOR を上げて PATCH を 0 にリセットします。それ以外の変更は、ユーザーがすぐに違いに気づく場合でも PATCH を上げます。どれほど目立つバグ修正でも、既存能力の中での速度や信頼性の改善でも、内部の書き換え、依存関係のアップグレード、ツール、ドキュメントでも同じです。1 つのコミットが両方の種類を含む場合は minor を上げますが、いずれか 1 つの変更がそれ単体で MINOR に当たるときだけです。MAJOR は明示的なメンテナー決定の後にのみ変更します。
エントリはコミット直前に、正確なステージ済み diff から準備します。

changelog は唯一の changelog 兼バージョン単位です。別のリリースノートファイルはありません。main ランタイムイメージのビルドがイメージペア検証を通過した後、ワークフローは最新バージョンをコントロールプレーンと Worker イメージタグに使い、その正確なセクションから不変の GitHub Release を作成します。changelog を変更の一部として扱い、後付けの書類仕事として扱わないでください。

正しいチェックを実行する

CONTRIBUTING.md はチェックを名付け、kit CLI reference はコマンドを文書化しています。形:

変更したパッケージの対象テストと通常の静的チェック — 影響を受けるパッケージのテストを実行します。スイート全体ではありません。
影響を受ける統合・エンドツーエンドスイート — 変更がプロセス、provider、永続化再起動、ユーザーフロー境界をまたぐ場合。スキップしないでください。
bun run analyze（kit analyze all）— リポジトリ全体の臭い、未使用コード、構造、循環。
コミット前に bun run lint と bun run fmt:check。

必要なコマンドが環境で実行できない場合は、正確なコマンドとブロッカーを報告してください。保証を検証済みとして主張しないでください。

プルリクエストを提出する

CONTRIBUTING.md は PR の手順をカバーしています。短い形: PR のコミットは changelog ルール（1 コミット 1 バージョン）に従い、変更は AGENTS.md の境界を尊重し、PR の説明はドキュメントが使う言葉で何を変えたか、なぜかを述べます。レビューも同じことをチェックします。

このガイドがそうでないもの

2 つのドキュメントの代わりではありません。それらへの扉です。読まずに編集する許可証ではありません。AGENTS.md は意図的に短く、読むことはコントリビューションができる最も安いことです。そしてルールを議論する場所でもありません。ルールは決着済みのトレードオフであり、ローカルな好みは発見事項ではありません — 選択された方向の中で実装が一貫しているかを評価してください。

次のステップ

最初の編集の前に AGENTS.md を読んでください。
セットアップと受入は CONTRIBUTING.md に従ってください。
devkit コマンドには kit CLI reference を使ってください。
変更がまたぐサブシステム境界を理解するには、architecture overview を読んでください。