Capacitor Guía de Contribución de Plugins

Capacitor plugins conectan tecnologías web con características de dispositivos nativos, permitiendo desarrollo de aplicaciones de múltiples plataformasEsta guía te ayuda:

• Configura tu entorno: Herramientas como Node.js, Xcode, y Android Studio son fundamentales.
• Sigue los estándares de Code: Utiliza TypeScript, Swift, y Kotlin con convenciones de nombres y manejo de errores consistentes.
• Prueba exhaustivamente: Escribe pruebas unitarias para JavaScript, iOS y Android para garantizar la confiabilidad.
• Documenta con claridad: Utiliza JSDoc y archivos README para una adopción fácil.
• Enviar una solicitud de extracción: Asegúrate de que la calidad sea alta, code, las pruebas y la documentación antes de contribuir.

Guía completa para código abierto - Cómo contribuir

Configuración del Entorno de Desarrollo

La configuración de un entorno de desarrollo adecuado es fundamental para el desarrollo eficiente de plugins. 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úrate de tener las siguientes herramientas instaladas:

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

Configuración de la Repósitorio 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. Fork y Clona el Repositorio
   Comienza forkeando el repositorio de Capacitor plugins en GitHub. Luego, clona tu repositorio forkeado:

   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 Versión
   Utiliza ramas de características para tus cambios y mantén sincronizada tu rama con el repositorio upstream.

Preparar Plataformas Nativas

Para el desarrollo cruzado, necesitarás configurar tanto el entorno iOS como Android.

Para iOS:

• Descarga Xcode desde la Mac App Store.

• Instala herramientas de línea de comandos con:

  xcode-select --install

• Instala CocoaPods con:

  sudo gem install cocoapods

• Configura una cuenta de desarrollador de Apple y los certificados necesarios.

• Utiliza 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 correctamente el SDK de Android 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, siga estas directrices para crear plugins que sean fáciles de mantener y usar.

Guía de estilo de Compliance

El ecosistema de plugins de Capacitor impone estrictos estándares de codificación utilizando herramientas como ESLint, Prettier, y SwiftLint. Aquí tienes un breve resumen de la formación requerida:

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

Administración de Errores y Tipos

Un manejo de errores consistente es crucial 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

Una buena documentación 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 funcionen con @capacitor/docgenPor 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: Incluya información esencial como pasos de instalación, instrucciones de configuración, requisitos específicos de plataforma, ejemplos de uso y una referencia detallada API.

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

sbb-itb-f9944d2

Guía de Pruebas de Plugin

Las pruebas de los plugins Capacitor implican centrarse en unas pocas áreas críticas para garantizar una funcionalidad suave y confiable.

Pruebas de Puente Nativo

Las pruebas de puente nativo garantizan una comunicación adecuada entre JavaScript y code. Para empezar, configure su entorno de prueba con marcos adaptados a cada plataforma.

Aquí hay un ejemplo de un Jest prueba unitaria 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 la prueba 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 hayas confirmado que la funcionalidad de la puente básica funciona como se espera, pasa a probar flujos de trabajo de usuario completos.

Pruebas de Plugin Completas

Para asegurarte de que tu plugin se desempeña bien en diferentes escenarios, prueba varias categorías:

Para plugins con características complejas, simula escenarios de usuario del mundo real. Por ejemplo, si estás probando un plugin de DeviceInfo, verifica:

• 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 ofrece herramientas de código abierto para implementar y probar actualizaciones de manera rápida. Aquí está cómo utilizarlas:

1. Configuración canales de actualización como dev, staging y producción.
2. Automatizar despliegues con herramientas CI/CD.
3. Enviar actualizaciones de manera instantánea.
4. Monitorear rendimiento y problemas a través de la Capgo panel de control.

Para lanzamientos en fases, Capgo te permite limitar las actualizaciones a un pequeño porcentaje de usuarios. Por ejemplo, puedes lanzar 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 hayas probado exhaustivamente tus cambios, sigue estos pasos para enviar tu solicitud de revisión:

Lista de Verificación de Solicitud de Revisión

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

- Actualice el README, la documentación inline y el CHANGELOG según sea necesario.

Directrices de la comunidad

• Al colaborar, siga estas mejores prácticas:
• Responda rápidamente a los comentarios de los revisores.
• Use GitHub’s suggestion feature to propose code changes.
• Utilice la función de sugerencia de __CAPGO_KEEP_0__ para proponer __CAPGO_KEEP_1__ cambios.

Envíe solicitudes de extracción pequeñas y enfocadas que aborden un solo función o problema a la vez. Si se trata de 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.

Capgo Guía de Integración

Si su plugin involucra actualizaciones en vivo, asegúrese de que funcione de manera fluida con Capgo antes de enviarlo:

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 de CI/CD para automatizar los despliegues de actualizaciones.

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 su plugin, es importante seguir el proceso establecido y cumplir con los estándares de la comunidad. Esto incluye seguir las directrices de codificación de Capacitor y probar su trabajo exhaustivamente.

La lista de verificación de PR destaca la necesidad de envíos de alta calidad. Si su plugin admite actualizaciones en vivo, integrar con Capgo (como se mencionó anteriormente) puede ayudarlo a liberar actualizaciones rápidamente sin tener que esperar aprobaciones de las tiendas de aplicaciones.

Una vez que su PR se haya fusionado, manténgase involucrado siguiendo los problemas y liberando actualizaciones de versiones. La interacción regular con la comunidad, el mantenimiento consistente y manteniéndose al día con Capacitor actualizaciones asegurará que su plugin permanezca útil y relevante.

Preste atención a los comentarios de los usuarios y realice actualizaciones según sea necesario. Este esfuerzo continuo ayuda a mantener la calidad general del ecosistema y mantiene su plugin valioso para los desarrolladores.

Siga adelante desde la Guía de Contribución de Plugin de Capacitor

Si está utilizando la Guía de Contribución de Plugin de Capacitor para planificar el trabajo de plugin nativo, conecte con el Directorio de Plugin de Capgo para el flujo de trabajo del producto en el Directorio de Plugin de Capgo los Plugins de Capacitor por Capgo para los detalles de implementación en los Plugins de Capacitor por Capgo Agregar o Actualizar Plugins para los detalles de implementación en Agregar o Actualizar Plugins, Alternativas de Plugins de Ionic Enterprise para el flujo de trabajo del producto en Alternativas de Plugins de Ionic Enterprise, y Capgo Compilaciones Nativas para el flujo de trabajo del producto en Capgo Compilaciones Nativas.