コントリビューション
Elftia へのコントリビューションにご興味をお持ちいただきありがとうございます。このドキュメントでは、開発に参加するための完全なワークフローを説明します。
開発環境のセットアップ
詳細な手順については、ローカル開発 ガイドを参照してください。概要は以下の通りです。
{/* Prerequisites */}
{/* Node.js v24 (see .nvmrc) + native build tools */}
git clone <repo-url> elftia
cd elftia
npm install
cp .env.example .env
npm run dev
ブランチ戦略
| ブランチ | 目的 | 保護ルール |
|---|---|---|
main | 安定リリース、常にリリース可能な状態 | PR + レビュー必須 |
dev/* | 機能開発ブランチ | - |
fix/* | バグ修正ブランチ | - |
ブランチ命名規則
{/* New feature */}
git checkout -b dev/feature-name
{/* Bug fix */}
git checkout -b fix/bug-description
{/* Examples */}
git checkout -b dev/notes-feature
git checkout -b fix/chat-scroll-issue
コード規約
完全な仕様については、コード規約 を参照してください。主なポイントは以下の通りです。
ESLint
- error レベルのルールはコミットをブロックします（import の順序、
no-var、eqeqeq、prefer-const、Hook のルール） - warn レベルのルールはコミットを許可しますが、修正を推奨します
- Husky はコミット前に自動的に
eslint --fixを実行します
ファイルサイズ
| ファイルタイプ | 推奨上限 | 絶対上限 |
|---|---|---|
| React コンポーネント | 400 行 | 800 行 |
| カスタム Hook | 300 行 | 600 行 |
| ユーティリティ関数 | 150 行 | 300 行 |
| 型定義 | 100 行 | 200 行 |
| サービス | 300 行 | 600 行 |
命名規則
- コンポーネント：PascalCase（
UserMessage.tsx） - Hook：usePascalCase（
useChatActions.ts） - ディレクトリ：kebab-case（
chat-messages/） - セマンティックトークンを使用（カラーのハードコーディング禁止）
コミット規約
Conventional Commits フォーマットを使用します。
<type>: <description>
[optional body]
[optional footer]
タイプ一覧
| タイプ | 説明 | 例 |
|---|---|---|
feat | 新機能 | feat: add notes export feature |
fix | バグ修正 | fix: resolve chat scroll position reset |
refactor | リファクタリング | refactor: split ChatInterface into smaller components |
docs | ドキュメント | docs: update IPC channels reference |
style | コードフォーマット（ロジック変更なし） | style: fix import ordering |
test | テスト | test: add unit tests for useFavorites |
chore | ビルド・ツール変更 | chore: update Vite to v7.1 |
例
git commit -m "feat: add favorites feature with session-scoped bookmarks
- Add FavoritesService with SQLite persistence
- Add FavoritesRouter with Zod validation
- Add useFavorites hook and FavoritesList component
- Add i18n support for en/zh/ja"
プルリクエストの要件
基本原則
- 1 つの PR は 1 つのことのみ行う — 機能開発とバグ修正を混在させない
- テスト — 新機能にはテストを含める
- ドキュメント — 必要に応じてドキュメントを更新する
- CI パス — すべてのチェックを通過する
PR タイトル
Conventional Commits フォーマットで変更内容を簡潔に記述します。
feat: add favorites feature
fix: resolve chat message duplication
refactor: extract message rendering into separate components
PR 説明テンプレート
## Changes
- Brief description of change 1
- Brief description of change 2
## How to Test
- [ ] Manual test step 1
- [ ] Manual test step 2
- [ ] Unit tests pass
## Screenshots (if UI changes)
新機能開発チェックリスト
完全なエンドツーエンドの流れについては、機能の追加 を参照してください。
バックエンド
| ステップ | ファイルの場所 | 説明 |
|---|---|---|
| 1. 共有型 | packages/desktop/app/shared/contracts/ | フロントエンドとバックエンドで共有する型定義 |
| 2. サービス | packages/desktop/app/main/services/ | ビジネスロジックのカプセル化 |
| 3. ルーター | packages/desktop/app/main/services/routers/ | IPC ルーティング + Zod バリデーション |
| 4. 登録 | routers/index.ts → registerAllRouters() | インスタンス作成と登録 |
| 5. プリロード | packages/desktop/app/preload/index.ts | フロントエンドへの公開 |
フロントエンド
| ステップ | ファイルの場所 | 説明 |
|---|---|---|
| 1. Hook | packages/renderer/src/features/<feature>/hooks/（複数フィーチャーをまたぐ Hook は shared/hooks/ へ） | データ取得と状態管理 |
| 2. コンポーネント | packages/renderer/src/features/<feature>/components/（共通 UI は components/ui/ へ） | UI レンダリング |
| 3. ルート | app/lazy/（pages.tsx など）+ app/App.tsx | 新しいページはレイジーロード登録が必要（旧来の from '../lazy' による lazy/index.ts バレルのインポートパスも引き続き使用可能） |
| 4. i18n | packages/renderer/src/locales/{en,zh,ja}/ | 3 言語の翻訳 |
ドキュメント
| 条件 | 更新が必要な対象 |
|---|---|
| 新しいモジュールを追加した場合 | .claude/skills/architecture-index/SKILL.md |
| ユーザー向けの機能の場合 | docs/elfi-kb/ 知識ベース |
| 新しいルートを追加した場合 | docs/elfi-kb/INDEX.md マッピングテーブル |
コードレビューのチェックポイント
フロントエンド / バックエンドの分離
- フロントエンドはユーザー入力と設定パラメーターのみを渡しているか？
- バックエンドがすべての外部呼び出しを処理しているか？
- 返されるデータは最終的な形式になっているか？
- base64 などの大容量データを IPC 経由でやり取りすることを避けているか？
セキュリティ
- Router のパラメーターは Zod で検証されているか？
- API キーはメインプロセスのみで使用されているか？
- XSS のリスクが潜在していないか？
ファイルサイズ
- 新しいファイルは推奨上限内に収まっているか？
- 変更したファイルが警告しきい値を超えていないか？
- 分割が必要ではないか？
エラーハンドリング
- ネットワークリクエストに try-catch があるか？
- エラーメッセージはユーザーフレンドリーか？
- 適切なローディング状態と空状態が存在するか？
ドキュメント
- アーキテクチャインデックスは更新されているか？
- 知識ベースは更新されているか？
- 3 つの i18n 言語は同期されているか？
バグレポート
レポートテンプレート
## Environment
- OS: Windows 11 / macOS 15 / Ubuntu 24
- Elftia version: v0.5.0
- Node.js version: v24.x
## Steps to Reproduce
1. Open the settings page
2. Switch to the "Appearance" tab
3. Click on wallpaper settings
4. After selecting an image...
## Expected Behavior
The wallpaper should display normally.
## Actual Behavior
The wallpaper does not display; console error: TypeError: Cannot read property 'path' of undefined
## Additional Information
- Diagnostic data export (Settings → Advanced → Export Diagnostic Data)
- Screenshots or screen recordings
- Console error logs
診断データのエクスポート
アプリ内から診断データをエクスポートして、問題のトラブルシューティングに役立てることができます。
Settings → Advanced → Diagnostic Tools → Export Diagnostic Data
または DevTools Console 経由で実行します。
const data = await window.api.diagnostics.bundle({ includeLogs: true });
連絡先
- Project Issues — 機能リクエストとバグレポート
- Pull Requests — コードのコントリビューション
- Discussions — 技術的な議論と質問