Capacitor Guía de contribución de plugins

Capacitor Los plugins conectan tecnologías web con características de dispositivos nativos, lo que permite desarrollo de aplicaciones de múltiples plataformas. Esta guía te ayuda a:

• Configurar tu Entorno: Herramientas como Node.js, Xcode, y Android Studio son fundamentales.
• Siga los estándares de Code: Utilice TypeScript, Swift, y Kotlin con convenciones de nombres y manejo de errores consistentes.
• Pruebe exhaustivamente: Escribe pruebas unitarias para JavaScript, iOS, y Android para garantizar la confiabilidad.
• Documente con claridad: Utilice JSDoc y archivos README para una adopción fácil.
• Enviar una Solicitud de Extracción: Asegúrese de que el code tenga una alta calidad, pruebas y documentación antes de contribuir.

Guía Completa para Open Source - Cómo Contribuir

Configuración del Entorno de Desarrollo

Crear un entorno de desarrollo adecuado es clave para el desarrollo de plugins eficiente. Una configuración bien preparada permite una codificación, prueba y despliegue suaves de sus plugins.

Herramientas y Habilidades que Necesitarás

Antes de empezar, asegúrese de que tenga las siguientes herramientas instaladas:

Debería estar cómodo con TypeScript para el desarrollo web y, por lo tanto, Swift (para iOS) o Java/Kotlin (para Android) para tareas de desarrollo nativo [1][2].

Configuración de la Repertorio Monolítico

El Capacitor plugins El ecosistema se basa en una estructura de monorepo. Este enfoque garantiza que tu trabajo se alinee con los estándares de la comunidad desde el principio.

1. Hacer una copia y clonar el repositorio
   Comienza clonando el repositorio de Capacitor plugins en GitHub. Luego, clona tu repositorio clonado:

   git clone https://github.com/your-username/capacitor-plugins.git
   cd capacitor-plugins
   npm install

2. Instalar Dependencias y Compilar
   Ejecuta el siguiente comando para instalar todo lo que necesitas y compilar los plugins:

   npm run build

3. Configurar Control de Versiones
   Utiliza ramas de características para tus cambios y mantén tu copia sincronizada con el repositorio upstream.

Preparar Plataformas Nativas

Para el desarrollo de múltiples plataformas, necesitarás configurar tanto el entorno iOS como Android.

Para iOS:

• Descarga Xcode desde la Tienda de Aplicaciones de Mac.

• Instale herramientas de línea de comandos utilizando:

  xcode-select --install

• Instale CocoaPods con:

  sudo gem install cocoapods

• Configure un cuenta de desarrollador de Apple y los certificados necesarios.

• Utilice SwiftLint (opcional) para mantener la calidad de code.

Para Android:

• Instale Android Studio junto con la última SDK y una dispositivo virtual.
• Asegúrese de tener instalado un JDK.
• Configure el SDK de Android correctamente dentro de Android Studio.

Una vez que estén configuradas estas plataformas, estará listo para seguir las prácticas de codificación establecidas y sumergirse en el desarrollo de plugins.

Code Standards Guide

Ahora que su entorno de desarrollo está configurado, manténgase a estos lineamientos para crear plugins que sean fáciles de mantener y utilizar.

Guía de Estilo de Cumplimiento

The ecosistema de plugins de Capacitor utiliza herramientas como ESLint, Prettier, y SwiftLint para imponer estrictos estándares de codificación. Aquí hay una visión general rápida de los formatos requeridos:

Los plugins deben utilizar TypeScript para una mayor seguridad de tipos y características de ES6+ como async/awaitAdemás, sigan las convenciones de codificación específicas de plataforma para Swift (iOS) y Kotlin (Android).

Gestión de errores y tipos

Es crucial un manejo de errores consistente para la compatibilidad entre plataformas. Aquí hay un ejemplo:

async checkPermissions(): Promise<PermissionStatus> {
  try {
    const result = await this.implementation.checkPermissions();
    return result;
  } catch (error) {
    throw new Error(`Permission check failed: ${error.message}`);
  }
}

Para la seguridad de tipos:

• Utilice interfaces enfocadas en casos de uso específicos.
• Aplicar tipos de unión para variaciones específicas de plataforma.

Code Documentación

La documentación adecuada es clave para hacer que tu plugin sea accesible y fácil de usar. Sigue estas prácticas:

1. API Documentación: Escribe comentarios de JSDoc que funcionan con @capacitor/docgen. Por ejemplo:

/**
 * @description Get the device's current battery level
 * @returns Promise with the battery level percentage
 */
async getBatteryLevel(): Promise<{ level: number }>;

2. Estructura de README: Incluye información esencial como instrucciones de instalación, configuración, requisitos específicos de plataforma, ejemplos de uso y una referencia detallada API.

Una documentación bien escrita garantiza que tu plugin sea fácil de adoptar y contribuye a la comunidad Capacitor más amplia.

sbb-itb-f9944d2

Guía de Pruebas de Plugin

La prueba de plugins Capacitor implica centrarse en unas pocas áreas críticas para garantizar una funcionalidad suave y confiabilidad.

Pruebas de Puente Nativo

La prueba de puentes nativos garantiza una comunicación adecuada entre JavaScript y code. Para empezar, configura tu entorno de prueba con marcos adaptados a cada plataforma.

Aquí hay un ejemplo de un Jest prueba de unidad para el lado de JavaScript:

// Example of a Jest unit test for the JavaScript bridge
describe('DeviceInfo Plugin', () => {
  test('getBatteryLevel returns valid percentage', async () => {
    const result = await DeviceInfo.getBatteryLevel();
    expect(result.level).toBeGreaterThanOrEqual(0);
    expect(result.level).toBeLessThanOrEqual(100);
  });
});

Para probar en el lado nativo, utilice XCTest para iOS y JUnit para Android. A continuación, se muestra un ejemplo para Android:

@Test
fun testBatteryLevel() {
    val plugin = DeviceInfo()
    val result = plugin.getBatteryLevel()
    assertTrue(result.level in 0..100)
}

Una vez que haya confirmado que la funcionalidad de la puente básica funciona como se espera, pase a probar flujos de trabajo de usuario completos.

Pruebas de Plugin Completas

Para asegurarse de que su plugin se desempeña bien en diferentes escenarios, pruebe varias categorías:

Para plugins con características complejas, simule escenarios de usuarios del mundo real. Por ejemplo, si está probando un plugin de DeviceInfo, verifique:

• Subidas exitosas bajo diferentes condiciones de red
• Informes de progreso precisos
• Uso de memoria durante transferencias de archivos grandes

Pruebas de actualizaciones OTA con Capgo

Capgo herramientas de código abierto facilitan la implementación y prueba de actualizaciones de manera rápida. Aquí está cómo utilizarlas:

1. Configuración canales de actualización como dev, staging y producción.
2. Automatice los despliegues con herramientas CI/CD.
3. Actualice instantáneamente.
4. Monitoree el rendimiento y problemas a través de la Capgo consola de administración.

Para despliegues en fases, Capgo le permite limitar las actualizaciones a un pequeño porcentaje de usuarios. Por ejemplo, puede desplegar una nueva versión a un 25% de usuarios cada 24 horas:

// Example configuration for staged rollout
{
  "plugin": "camera-plugin",
  "version": "1.2.0",
  "rollout": {
    "percentage": 25,
    "interval": "24h"
  }
}

Esta aproximación en fases ayuda a identificar problemas temprano aprovechando la retroalimentación de la comunidad antes de una liberación completa.

Proceso de Solicitud de Revisión

Una vez que haya probado exhaustivamente sus cambios, siga estos pasos para enviar su solicitud de revisión:

Lista de Verificación de Solicitud de Revisión

Antes de enviar, asegúrese de haber cubierto estas áreas clave:

Directrices de la comunidad

Al colaborar, siga estas mejores prácticas:

• Responda rápidamente a los comentarios de los revisores.
• Mantenga las discusiones enfocadas en detalles técnicos.
• Utilice la función de sugerencias de GitHub para proponer code cambios.
• Envíe solicitudes de extracción pequeñas y enfocadas que aborden un solo feature o problema a la vez.

Para cambios más grandes, es una buena idea crear un problema primero y discutir su enfoque. El equipo de Capacitor depende de GitHub Actions para verificaciones automatizadas, y todas las verificaciones deben pasar antes de que su solicitud de extracción pueda ser revisada.

Guía de Integración de Capgo

Si su plugin involucra actualizaciones en vivo, asegúrese de que funcione sin problemas con Capgo antes de enviarla:

1. Control de Versión
   Utilice una versión semántica clara para su plugin, y documente todos los cambios en el changelog. El sistema de Capgo ayuda a rastrear la adopción de versiones en dispositivos de los usuarios.

2. Integración CI/CD
   Integre Capgo en su pipeline CI/CD para automatizar las actualizaciones de despliegue.

3. Monitoreo de Actualizaciones
   Monitoree las tasas de éxito de despliegue y asegúrese de cumplir con las directrices de las tiendas de aplicaciones.

Resumen

Para hacer una contribución significativa con tu plugin, es importante seguir el proceso establecido y cumplir con los estándares de la comunidad. Esto incluye adherirse a las directrices de codificación de Capacitor y probar exhaustivamente tu trabajo.

La lista de verificación de PR destaca la necesidad de presentaciones de alta calidad. Si tu plugin admite actualizaciones en vivo, integrar con Capgo (tal como se mencionó anteriormente) puede ayudarte a publicar actualizaciones rápidamente sin tener que esperar aprobaciones de las tiendas de aplicaciones.

Una vez que se ha fusionado tu PR, sigue involucrado siguiendo los problemas y publicando actualizaciones de versión. La interacción regular con la comunidad, la mantenimiento consistente y manteniéndote al día con las actualizaciones de Capacitor asegurará que tu plugin siga siendo útil y relevante.

Ten en cuenta la retroalimentación de los usuarios y haz actualizaciones según sea necesario. Este esfuerzo continuo ayuda a mantener la calidad general del ecosistema y mantiene tu plugin valioso para los desarrolladores.

Sigue adelante desde la Guía de Contribución de Plugins de Capacitor

Si estás utilizando la Guía de Contribución de Plugins de Capacitor para planificar el trabajo de plugins nativos, conecta con la Dirección de Plugins de Capgo para el flujo de trabajo del producto en el directorio de plugins Capgo Capacitor Plugins por Capgo para el detalle de implementación en Capacitor Plugins por Capgo, Agregar o Actualizar Plugins para el detalle de implementación en Agregar o Actualizar Plugins, Alternativas de Plugins de Empresa Ionic para el flujo de trabajo del producto en Alternativas de Plugins de Empresa Ionic, y Capgo Compilaciones Nativas para el flujo de trabajo del producto en Capgo Compilaciones Nativas.