貢献ガイド

はじめに

ステップ 1: リポジトリをフォークし、ローカルマシンにクローンを作成します。

# Clone the repository from your fork
git clone https://github.com/xxxxx/read-frog.git

# Enter the project directory
cd read-frog

# Add the upstream remote to sync with the original repository
git remote add upstream https://github.com/mengxi-ream/read-frog.git

ステップ 2: 依存関係をインストールして開発を開始する

# Install dependencies
pnpm i

# Start the development server
pnpm dev

これにより、拡張機能の開発環境が開始されます。拡張機能はデフォルトのブラウザで自動的に開きます。

開発のヒント

pnpm Node.js 管理での npx の使用

pnpm の組み込み Node.js バージョン管理 (pnpm 10.14 で導入) を使用しています。 npx コマンドを実行すると、EBADDEVENGINES エラーが発生する場合があります。解決策は 2 つあります。

解決策 1: npx の代わりに pnpm dlx または pnpx を使用します

# Instead of npx
npx some-package@latest

# Use pnpm dlx
pnpm dlx some-package@latest

# Or use pnpx (alias for pnpm dlx)
pnpx some-package@latest

解決策 2: Node.js バージョンと pnpm を調整する

npx を置き換えるのが不便な場合 (たとえば、Claude Code 内のユーザースコープの MCP インストールの場合)、Node.js バージョンを調整します。

# Install and use the required Node.js version globally
pnpm env use --global 22.18.0

特定のブラウザで拡張機能を開きます

ルートディレクトリに /modify または web-ext.config.ts ファイルを作成して、ブラウザのパスを明示的に指定できます。

// web-ext.config.ts
import { defineWebExtConfig } from 'wxt';

export default defineWebExtConfig({
  binaries: {
      chrome: "path/to/your/chrome.exe",
      firefox: "path/to/your/firefox.exe",
      edge: "path/to/your/edge.exe"
    }
});

pnpm 開発者は拡張機能を自動的にロードできません

Chrome バージョン 137 以降を使用している場合は、開発用に Chrome for Testing をダウンロードする必要があります。 detailsを参照してください。

永続的な Chrome プロファイル

デフォルトでは、web-ext は開発スクリプトを実行するたびに新しいプロファイルを作成します。

開発セッション間でログイン、devtools 拡張機能、ブラウザ設定を保持したい場合は、プロジェクトルートで web-ext.config.ts を作成または更新します。

永続プロファイルの構成は、オペレーティングシステムによって若干異なります。

// web-ext.config.ts
import { defineWebExtConfig } from 'wxt';

export default defineWebExtConfig({
  chromiumArgs: ['--user-data-dir=./.wxt/chrome-data'],
});

Windows では、WXT は chromiumProfile と keepProfileChanges の使用を推奨します。 chromiumProfile パスは絶対パスである必要があるため、node:path の resolve を使用します。

利点: プロファイルは開発セッション間で保持されるため、次のことが可能になります。

devtools 拡張機能をインストールする
ログインを記憶する
ブラウザの設定を維持する

💡 ヒント: 永続プロファイルは Chromium ブラウザにのみ適用されます。例の .wxt/chrome-data を置き換えて、プロジェクトごとに個別のプロファイルディレクトリを使用できます。

開発モードでの Google ログインの問題

開発モードで Google アカウントを使用してログインし、「このブラウザまたはアプリは安全ではない可能性があります。」 というエラーが発生した場合は、自動検出を無効にする必要があります。

解決策: chromiumArgs を web-ext.config.ts に追加します。

// web-ext.config.ts
import { defineWebExtConfig } from 'wxt';

export default defineWebExtConfig({
  chromiumArgs: ['--disable-blink-features=AutomationControlled'],
});

これにより、Google が自動ブラウザからのログイン試行をブロックする自動検出が無効になります。

ブレークポイントのデバッグの問題

⚠️ ブレークポイントのデバッグで問題が発生した場合は、Chrome DevTools の無視リスト設定が原因である可能性があります。拡張機能によって挿入されたコンテンツスクリプトは自動的に無視され、ブレークポイントが失敗する可能性があります。

解決策:

任意の Web ページで DevTools を開く
右上隅にある設定アイコン (⚙️) をクリックします
左側のナビゲーションから「リストを無視」を選択します
[拡張機能によって挿入されたコンテンツスクリプト] オプションが オフになっていることを確認します

Chrome Ignore List

macOS: 開いているファイルが多すぎるエラー (EMFILE)

pnpm dev の実行時に macOS でこのエラーが発生した場合:

Emfile Error

これは、Chokidar (Vite/WXT) で使用されるファイル監視ライブラリ) がデフォルトで macOS のネイティブ FSEvents を使用するため、監視対象ファイルごとにファイル記述子が必要になります/directory. 大きなプロジェクトではシステム制限を超える可能性があります。

解決策: CHOKIDAR_USEPOLLING=true を設定して、ファイル記述子を必要としないポーリングモードに切り替えます。

プロジェクトルートで .env ファイルを作成または更新します。

# .env
CHOKIDAR_USEPOLLING=true

これ以降、pnpm dev は EMFILE エラーなしで動作するようになります。

注意: ポーリングモードは若干遅くなり、より多くの CPU を使用しますが、ファイル記述子の制限の問題は回避されます。

コードの送信

新しいブランチを作成する

# For new features
git checkout -b feat/the-feature

# For bug fixes
git checkout -b fix/the-bug

# For docs modify
git checkout -b docs/the-docs

ブランチをマージ

リモートのメインブランチが更新されて PR で競合が発生した場合は、事前にリモートブランチをマージすることで問題を解決できます。 .

# Switch to the main branch
git checkout main

# Pull the latest code from upstream
git pull upstream main

# Switch back to your local branch
git checkout docs/xxxx

# Merge the main branch into your local branch
git rebase main

# Push the code again if there are conflicts after rebase
git push --force-with-lease origin docs/xxxx

# If there are no conflicts, push the code again
git push origin docs/xxxx

上流リポジトリの同期で致命的になる

上流リポジトリの同期中にこのエラーが発生した場合

fatal: 'upstream' does not appear to be a git repository
fatal: Could not read from remote repository.

これは、アップストリームリモートがステップ 1 で構成されていないことを意味します。ここで追加します。

git remote add upstream https://github.com/mengxi-ream/read-frog.git

プルリクエストの生成

プルリクエストを生成する前に、変更セットを追加して変更を文書化する必要があります。

バージョンバンプを理解する

変更に基づいて、適切なバージョンバンプタイプを選択します。

パッチ - バグ修正、タイプミス、ドキュメントの更新、マイナーな改善
- 例: 翻訳エラーの修正、README の更新、ボタンのスタイルの修正、パフォーマンスの向上
マイナー - 下位互換性のある新機能
- 例: 翻訳無効化ボタンの追加、語彙エクスポート機能の追加
メジャー - 既存の機能に影響を与える重大な変更
- 例: API 構造の変更、非推奨の機能の削除、大規模なリファクタリング

変更セットの追加

# Run the changeset command
pnpm changeset

# 1. Choose version bump type for each selected package
🦋  What kind of change is this for @read-frog/extension? (current version is 1.17.3)
❯ patch   # For bug fixes and minor improvements
  minor   # For new features
  major   # For breaking changes

# 2. Write a summary of your changes
🦋  Please enter a summary for this change (this will be in the changelog)
Summary >>> fix: translation button style

pnpm changeset を実行すると、マークダウンファイルが .changeset ディレクトリに生成されます。プルリクエストを作成する前に、このファイルを編集して、変更に関する詳細を提供できます。

次に、プルリクエストを作成し、マージされるまで待ちます。

コミット規約

コミットメッセージの書き込みには Conventional Commits 仕様を使用します。

環境変数を設定する

拡張機能の開発中に、開発環境の API キーなどの環境変数を自動的にロードするには、ルートディレクトリに .env.development ファイルを作成します。

# .env.development
WXT_OPENAI_API_KEY=xxx
WXT_DEEPSEEK_API_KEY=xxx

WXT は、Vite 規則に従って dotenv ファイルをロードします。 import.meta.env を介して拡張コードからアクセスする必要がある変数には、WXT_ プレフィックスを使用する必要があります。

1 つのコマンドに対して環境変数を設定する必要があるだけの場合、構文はシェルによって異なります。

SKIP_FREE_API=true pnpm test

デフォルトの Windows シェルは、macOS/Linux KEY=value command 構文をサポートしません。その理由でコマンドが失敗した場合は、上記の PowerShell または CMD フォームを使用してください。定期的に使用する WXT 変数の場合は、.env.development に入れることをお勧めします。

中国での Google API テストをスキップする

中国本土からの寄稿者の場合、コードをプッシュする必要がある場合は、次のコマンドを使用します。

SKIP_FREE_API=true git push

なぜこれが必要なのでしょうか?コードのテストはプッシュプロセス中に実行されますが、Google の無料の API は中国本土ではアクセスできないためです。これにより、テストが失敗し、プッシュが拒否されます。 SKIP_FREE_API 環境変数を設定することで、Google テストをスキップします。

どのような PR が検討され、統合されますか?

貢献を始めるには

これが最初の PR の 1 つで、真剣に貢献するつもりであれば、通常、品質の問題を理由に拒否されることはありません。メンテナは、問題を特定し、開発プロセスとコードスタイルに適応するのを支援します。ただし、次のガイドラインに従うことを強くお勧めします。

リポジトリ内の「Good First Issue」などの小さな問題から始めます。小さくてシンプルな PR により、スムーズな学習プロセスが実現します。
PR がすべての GitHub アクションとローカルテストに合格することを確認します。

私の PR がメンテナーによってレビューされないのはなぜですか?

コードベースに慣れる前に過度に複雑な PR を作成したため、必要な変更が多すぎます。
あなたのコードには多くの基本的なエラーが含まれており、メンテナーはあなたの真剣さを疑問視しています。
- 削除されなかった未使用のコードスニペット
- 過剰な反復コード
- 変数名や関数名が恣意的すぎる
- AI 支援開発を奨励していますが、AI が生成したコードを慎重にレビューしていないため、低品質、保守不能、または過剰設計のコードが発生しています。
メンテナは修正の提案を何度も提供しましたが、あなたがそれに従わなかったか、変更によって根本的な問題が解決されませんでした。

On this page