開発者ワークフローとコントリビューション

このドキュメントでは、kanade コードベースで作業するコントリビューター向けの標準的な開発ワークフロー、lint/テストの要件、および VCS ブランチのガイドラインについて説明します。

1. クオリティゲート (Pre-Push & CI)

プッシュや PR の送信を行う前に、ローカルのテストスイートがすべてグリーンである必要があります。これは GitHub Actions で実行される自動チェックと同じものです。

# Run formatting check, clippy checks, target tests, and cargo lock checks
cargo make check

FMT & Clippy: 私たちは厳格なゼロワーニングポリシーを維持しています。強力な設計上の正当な理由がない限り、#[allow(clippy::...)] を散布しないでください。
TDD (テスト駆動開発): Kent Beck の TDD 手法に従ってください。最初に失敗するテストを書いて「何を」行うかを定義し、次にそれを満たすコードを実装します。

2. `renri` によるワークツリー管理

隔離された機能開発のために、私たちは renri を使用して軽量なリポジトリワークツリーを管理します。これにより、ステージの汚染を防ぎ、メインチェックアウトをクリーンに保ち、瞬時にタスクを切り替えることができます。

なぜ `renri` なのか？

Git と Jujutsu (jj) がコロケーションされた環境では、ワークツリーを手動で管理するのは複雑になります。renri は、VCS 固有のワークツリー作成（設定されている場合は jj を優先）とクリーンアップを自動的にラッピングすることで、これを簡素化します。

よく使うコマンド

# Create an isolated worktree (uses Jujutsu by default if present)
renri add feat/your-awesome-feature

# Force a Git-native worktree (bypassing jj)
renri --vcs git add feat/your-awesome-feature

# Clean up and delete a worktree after merging
renri remove feat/your-awesome-feature

# Garbage-collect and prune stale or broken worktrees
renri prune

注意: ワークツリー作成時に自動的に cargo-make の on-add フックが呼び出され、リモートの参照を取得して APM 設定を直ちにセットアップします。

3. コロケーションされた Jujutsu (jj) & Git ワークフロー

開発環境は、Git と Jujutsu がコロケーションされるよう設定されています。ローカルのバージョン管理には、安全で競合のないコミットモデルを持つ jj を好んで使用します。

ガイドライン

main への直接プッシュ禁止: すべての変更は Pull Request 経由でマージされる必要があります。
ブランチ/ブックマークの命名規則:
- feat/... は新機能用。
- fix/... はバグ修正用。
- chore/... はインフラ、依存関係の更新、またはリリース用。
コミットメッセージ: コミットメッセージ、PR タイトル、本文は英語で記述してください。
バージョン更新: リリースのバージョン更新は、main への PR と自動タグ付けパイプラインを介してのみ管理されます。手動で git tag を実行しないでください。

4. ドキュメントポリシー

ドキュメントは、コードの変更と常に完全に同期している必要があります。機能を追加または変更した場合は常に、以下を実行してください:

コード内のコメントや docstring を更新し、「なぜ」そのようにしたのかを説明します（「どのように」やっているかを単に再記述するコメントは避けてください）。
関連する book ページ（book/src/ 配下に英語で記述）を更新します。
翻訳テンプレートジェネレーターを実行して、ローカライズカタログ（ポファイル）を同期します。

kanade — 奏