Руководство по вкладу

Начало работы

Шаг 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

Это запустит среду разработки расширений. Расширение автоматически откроется в браузере по умолчанию.

Советы по разработке

Использование npx с управлением pnpm Node.js

Мы используем встроенное в pnpm управление версиями Node.js (представленное в pnpm 10.14). Вы можете столкнуться с ошибками EBADDEVENGINES при выполнении команд npx. Есть два решения:

Решение 1. Используйте pnpm dlx или pnpx вместо npx

# 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 неудобно (например, для пользовательских установок MCP в Claude Code), выровняйте версию 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 создает новый профиль каждый раз, когда вы запускаете сценарий разработки.

Если вы хотите сохранить логины, расширения инструментов разработчика и настройки браузера между сеансами разработки, создайте или обновите 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 должен быть абсолютным, поэтому используйте resolve из node:path.

Преимущества: Ваш профиль сохраняется между сеансами разработки, поэтому вы можете:

• Установите расширения инструментов разработчика
• Запоминать логины
• Сохранить настройки браузера

💡Совет. Постоянные профили применимы только к браузерам 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. Сценарии содержимого, внедренные расширениями, могут автоматически игнорироваться, что приводит к сбою точек останова.

Решение:

1. Откройте DevTools на любой веб-странице.
2. Нажмите значок настроек (⚙️) в правом верхнем углу.
3. Выберите «Список игнорировать» на панели навигации слева.
4. Убедитесь, что параметр «Сценарии контента, внедренные расширениями» снят.

macOS: ошибка слишком большого количества открытых файлов (EMFILE)

Если вы столкнулись с этой ошибкой в macOS при запуске pnpm dev:

Это происходит потому, что Chokidar (библиотека наблюдения за файлами, используемая Vite/WXT), по умолчанию использует собственные FSEvents macOS, для которых требуется файловый дескриптор для каждого отслеживаемого файла/directory.. Большие проекты могут превышать системный предел.

Решение: Установите CHOKIDAR_USEPOLLING=true для переключения в режим опроса, который не требует файловых дескрипторов.

Создайте или обновите файл .env в корне проекта:

# .env
CHOKIDAR_USEPOLLING=true

После этого pnpm dev будет работать без ошибки EMFILE.

Примечание. Режим опроса немного медленнее и использует больше ресурсов ЦП, но позволяет избежать проблемы ограничения файлового дескриптора.

Отправка кода

Создать новую ветку

# 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.

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

Создание запроса на включение

Прежде чем генерировать запрос на включение, вам необходимо добавить набор изменений для документирования ваших изменений.

Понимание ошибок версий

Выберите подходящий тип обновления версии на основе ваших изменений:

• патч — исправления ошибок, опечатки, обновления документации, мелкие улучшения.
  • Пример: исправить ошибку перевода, обновить README, исправить стиль кнопок, повысить производительность.
• minor – новые функции, обратно совместимые.
  • Пример: добавить кнопку отключения перевода, добавить функцию экспорта словаря.
• значительный – критические изменения, влияющие на существующую функциональность.
  • Пример: изменение структуры 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 загружает файлы dotenv в соответствии с соглашениями Vite. Переменные, к которым необходимо получить доступ из кода расширения через import.meta.env, должны использовать префикс WXT_.

Если вам нужно установить переменную среды только для одной команды, синтаксис зависит от вашей оболочки:

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

Почему это необходимо? Потому что тесты кода выполняются во время процесса отправки, но бесплатный API от Google недоступен в материковом Китае. Это приведет к сбою тестов и отклонению отправки. Установив переменную среды SKIP_FREE_API, мы пропускаем тесты Google.

Какие PR будут рассмотрены и объединены?

Начало работы с вкладами

Если это один из ваших первых запросов на публикацию и вы серьезно настроены внести свой вклад, он, как правило, не будет отклонен из-за проблем с качеством. Специалисты по сопровождению помогут вам выявить проблемы и адаптироваться к нашему процессу разработки и стилю кода. Однако мы настоятельно рекомендуем следовать следующим рекомендациям:

1. Начните с небольших проблем, таких как «Хороший первый выпуск» в репозитории. Небольшие и простые PR обеспечивают плавный процесс обучения.
2. Убедитесь, что ваш PR прошел все действия GitHub и местные тесты.

Почему мой PR не проверяется сопровождающими?

1. Вы внесли слишком сложный PR до ознакомления с кодовой базой, что привело к слишком большому количеству необходимых изменений.
2. Ваш код содержит множество основных ошибок, что заставляет сопровождающих усомниться в вашей серьёзности:
   • Неиспользованные фрагменты кода, которые не были удалены
   • Чрезмерно повторяющийся код
   • Имена переменных и функций слишком произвольны.
   • Мы поощряем разработку с помощью ИИ, но вы не внимательно проверили сгенерированный ИИ код, что привело к низкому качеству, невозможности сопровождения или переусложнению кода.
3. Специалисты по сопровождению несколько раз предлагали изменения, но вы либо не следовали им, либо ваши изменения не устраняли коренные проблемы.