メインコンテンツまでスキップ

コントリビューション

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 行
カスタム Hook300 行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. Hookpackages/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. i18npackages/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 — 技術的な議論と質問