Guía de contribución

Empezando

Paso 1: bifurca el repositorio y clónalo en tu máquina local

# 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

Paso 2: instale las dependencias y comience el desarrollo

# Install dependencies
pnpm i

# Start the development server
pnpm dev

Esto iniciará el entorno de desarrollo de la extensión. La extensión se abrirá automáticamente en su navegador predeterminado.

Consejos de desarrollo

Usando npx con pnpm Node.js Gestión

Estamos utilizando la gestión de versiones Node.js integrada de pnpm (introducida en pnpm 10.14). Puede encontrar errores EBADDEVENGINES al ejecutar comandos npx. Hay dos soluciones:

Solución 1: Utilice pnpm dlx o pnpx en lugar de 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

Solución 2: Alinear la versión Node.js con pnpm

Cuando no sea conveniente reemplazar npx (por ejemplo, para instalaciones de MCP de ámbito de usuario en Claude Code), alinee su versión Node.js:

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

Abra la extensión en el navegador específico

Puede crear/modify el archivo web-ext.config.ts en el directorio raíz para especificar explícitamente la ruta del navegador.

// 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 dev no puede cargar la extensión automáticamente

Si usa Chrome versión 137 o superior, debe descargar Chrome for Testing para el desarrollo. Ver details.

Perfil de Chrome persistente

De forma predeterminada, web-ext crea un nuevo perfil cada vez que ejecuta el script de desarrollo.

Si desea conservar los inicios de sesión, las extensiones de devtools y la configuración del navegador entre sesiones de desarrollo, cree o actualice web-ext.config.ts en la raíz del proyecto.

La configuración del perfil persistente es ligeramente diferente entre los sistemas operativos:

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

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

En Windows, WXT recomienda usar chromiumProfile y keepProfileChanges. La ruta chromiumProfile debe ser absoluta, así que use resolve desde node:path.

Beneficios: Tu perfil persiste entre sesiones de desarrollo, por lo que puedes:

• Instalar extensiones de herramientas de desarrollo
• Recordar inicios de sesión
• Mantener la configuración del navegador

💡 Consejo: Los perfiles persistentes solo se aplican a los navegadores Chromium. Puede reemplazar .wxt/chrome-data en los ejemplos para usar un directorio de perfil separado para cada proyecto.

Problemas de inicio de sesión de Google en modo desarrollador

Si desea iniciar sesión con una cuenta de Google en modo de desarrollo y aparece el error "Es posible que este navegador o aplicación no sea seguro"., debe desactivar la detección de automatización.

Solución: Agregue chromiumArgs a su web-ext.config.ts:

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

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

Esto desactiva la detección de automatización que hace que Google bloquee los intentos de inicio de sesión desde navegadores automatizados.

Problemas de depuración de puntos de interrupción

⚠️ Si tiene problemas con la depuración de puntos de interrupción, puede deberse a la configuración de la lista de ignorados de Chrome DevTools. Los scripts de contenido inyectados por extensiones pueden ignorarse automáticamente, lo que provoca que fallen los puntos de interrupción.

Solución:

1. Abra DevTools en cualquier página web
2. Haga clic en el ícono de configuración (⚙️) en la esquina superior derecha
3. Seleccione "Lista de ignorados" en la navegación izquierda
4. Asegúrese de que la opción "Scripts de contenido inyectados por extensiones" esté desmarcada

macOS: Error de demasiados archivos abiertos (EMFILE)

Si encuentra este error en macOS al ejecutar pnpm dev:

Esto sucede porque Chokidar (la biblioteca de observación de archivos utilizada por Vite/WXT) utiliza de forma predeterminada los FSEvents nativos de macOS, que requiere un descriptor de archivo para cada archivo observado/directory. Los proyectos grandes pueden exceder el límite del sistema.

Solución: Configure CHOKIDAR_USEPOLLING=true para cambiar al modo de sondeo, que no requiere descriptores de archivos.

Cree o actualice el archivo .env en la raíz del proyecto:

# .env
CHOKIDAR_USEPOLLING=true

Después de esto, pnpm dev funcionará sin el error EMFILE.

Nota: El modo de sondeo es ligeramente más lento y utiliza más CPU, pero evita el problema del límite de descriptores de archivos.

Envío de código

Crear una nueva sucursal

# 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

Fusionar rama

Si la rama principal remota se actualiza y crea conflictos en nuestro PR, puede resolverlo fusionando la rama remota con anticipación. .

# 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

Generando solicitud de extracción

Antes de generar una solicitud de extracción, debe agregar un conjunto de cambios para documentar sus cambios.

Comprensión de los cambios de versión

Elija el tipo de mejora de versión apropiado según sus cambios:

• parche - Corrección de errores, errores tipográficos, actualizaciones de documentación, mejoras menores
  • Ejemplo: corregir errores de traducción, actualizar README, corregir el estilo de los botones, mejoras de rendimiento
• menor - Nuevas funciones que son compatibles con versiones anteriores
  • Ejemplo: agregar un botón para desactivar la traducción, agregar una función de exportación de vocabulario
• importante: cambios importantes que afectan la funcionalidad existente
  • Ejemplo: cambiar la estructura API, eliminar características obsoletas, refactorización importante

Agregar un conjunto de cambios

# 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

Después de ejecutar pnpm changeset, se generará un archivo de rebajas en el directorio .changeset. Puede editar este archivo para proporcionar más detalles sobre sus cambios antes de crear la solicitud de extracción.

Luego cree una solicitud de extracción y espere a que se fusione.

Convención de compromiso

Usamos la especificación Conventional Commits para escribir mensajes de confirmación.

Establecer variables de entorno

Para cargar automáticamente variables de entorno mientras desarrolla la extensión, como claves API para el entorno de desarrollo, puede crear un archivo .env.development en el directorio raíz.

# .env.development
WXT_OPENAI_API_KEY=xxx
WXT_DEEPSEEK_API_KEY=xxx

WXT carga archivos dotenv siguiendo las convenciones Vite. Las variables a las que se debe acceder desde el código de extensión a través de import.meta.env deben usar el prefijo WXT_.

Si solo necesita configurar una variable de entorno para un único comando, la sintaxis depende de su shell:

SKIP_FREE_API=true pnpm test

Los shells predeterminados de Windows no admiten la sintaxis macOS/Linux KEY=value command. Si un comando falla por ese motivo, utilice el formulario PowerShell o CMD anterior. Para las variables WXT que usa regularmente, prefiera ponerlas en .env.development.

Omita las pruebas de Google API en China

Si es un colaborador de China continental, cuando necesite enviar código, utilice el siguiente comando:

SKIP_FREE_API=true git push

¿Por qué es esto necesario? Debido a que las pruebas de código se realizan durante el proceso de envío, el API gratuito de Google no está disponible en China continental. Esto provocaría que las pruebas fallaran y se rechazara el envío. Al configurar la variable de entorno SKIP_FREE_API, nos saltamos las pruebas de Google.

¿Qué tipo de RP se revisarán y fusionarán?

Comenzando con las contribuciones

Si este es uno de sus primeros RP y realmente desea contribuir, generalmente no será rechazado debido a problemas de calidad. Los mantenedores lo ayudarán a identificar problemas y adaptarse a nuestro proceso de desarrollo y estilo de código. Sin embargo, recomendamos encarecidamente seguir estas pautas:

1. Comience con problemas pequeños, como "Primer problema bueno" en el repositorio. Los RP pequeños y simples proporcionan un proceso de aprendizaje fluido.
2. Asegúrese de que su RP pase todas las acciones GitHub y pruebas locales.

¿Por qué los mantenedores no revisan mi PR?

1. Contribuiste con un PR demasiado complejo antes de familiarizarte con el código base, lo que resultó en demasiados cambios necesarios.
2. Su código contiene muchos errores básicos, lo que hace que los mantenedores cuestionen su seriedad:
   • Fragmentos de código no utilizados que no se eliminaron
   • Código excesivamente repetitivo
   • Los nombres de variables y funciones son demasiado arbitrarios
   • Fomentamos el desarrollo asistido por IA, pero usted no revisó cuidadosamente el código generado por IA, lo que generó un código de baja calidad, imposible de mantener o con demasiada ingeniería.
3. Los mantenedores proporcionaron sugerencias de modificación varias veces, pero usted no las siguió o sus cambios no solucionaron los problemas de raíz.