Guía de contribución para plugins de Capacitor

Capacitor los plugins conectan tecnologías web con funciones nativas del dispositivo, permitiendo el desarrollo de apps multiplataforma. Esta guía te ayuda a:

• Configura tu entorno: Herramientas como Node.js, Xcode, y Android Studio son esenciales.
• Sigue los estándares de Code: Usa TypeScript, Swift, y Kotlin con convenciones de nombres y manejo de errores consistentes.
• Testea a fondo: Escribe unit tests para JavaScript, iOS y Android para asegurar la fiabilidad.
• Documenta con claridad: Usa JSDoc y archivos README para facilitar la adopción.
• Envía un Pull Request: Asegura un code de alta calidad, testing y documentación antes de contribuir.

Guía completa de Open Source: Cómo contribuir

Configuración del entorno de desarrollo

Crear un entorno de desarrollo adecuado es clave para desarrollar plugins eficientemente. Un setup bien preparado permite programar, testear y desplegar tus plugins sin problemas.

Herramientas y habilidades necesarias

Antes de empezar, asegúrate de tener instaladas las siguientes herramientas:

También deberías sentirte cómodo con TypeScript para desarrollo web y con Swift (para iOS) o Java/Kotlin (para Android) para tareas de desarrollo nativo [1][2].

Configuración del Monorepo

El Plugins de Capacitor el ecosistema se basa en una estructura de monorepo. Así aseguras que tu trabajo cumpla con los estándares de la comunidad desde el principio.

1. Haz un Fork y Clona el Repositorio
   Empieza haciendo un fork del repositorio de plugins de Capacitor en GitHub. Luego, clona tu fork:

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

2. Instala las Dependencias y Haz el Build
   Ejecuta el siguiente comando para instalar todo lo necesario y hacer el build de los plugins:

   npm run build

3. Configura el Control de Versiones
   Usa feature branches para tus cambios y mantén tu fork sincronizado con el repositorio upstream.

Preparación de plataformas nativas

Para el desarrollo multiplataforma, deberás configurar los entornos de iOS y Android.

Para iOS:

• Descarga Xcode desde la Mac App Store.

• Instala las herramientas de CLI con:

  xcode-select --install

• Instala CocoaPods con:

  sudo gem install cocoapods

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

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

Para Android:

• Instala Android Studio junto con la última versión de SDK y un dispositivo virtual.
• Asegúrate de tener instalado un JDK.
• Configura correctamente el SDK de Android en Android Studio.

Una vez configuradas estas plataformas, estarás listo para seguir las prácticas de código establecidas y adentrarte en el desarrollo de plugins.

Guía de estándares de Code

Ahora que tu entorno de desarrollo está listo, sigue estas pautas para crear plugins fáciles de mantener y usar.

Cumplimiento de la guía de estilo

El ecosistema de plugins de Capacitor impone estándares de código estrictos usando herramientas como ESLint, Prettier, y SwiftLint. Aquí tienes un resumen rápido del formato requerido:

Los plugins deben usar TypeScript para mejorar el tipado y aprovechar ES6+, como async/await. Además, sigue las convenciones de código de Swift (iOS) y Kotlin (Android).

Gestión de Errores y Tipos

Un manejo de errores consistente es clave para la compatibilidad multiplataforma. Aquí 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 mayor seguridad de tipos:

• Usa interfaces específicas adaptadas a cada caso de uso.
• Aplica union types para variaciones según la plataforma.

Documentación de Code

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

1. Documentación de API: Escribe comentarios JSDoc que funcionen 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 del README: Incluye info esencial como pasos de instalación, configuración, requisitos por plataforma, ejemplos de uso y una referencia detallada de API.

Una documentación bien escrita facilita la adopción de tu plugin y ayuda a la comunidad de Capacitor.

sbb-itb-f9944d2

Guía de testing de plugins

Testear plugins de Capacitor requiere enfocarse en áreas críticas para garantizar su funcionalidad y fiabilidad.

Tests del Native Bridge

El testing del native bridge asegura la comunicación entre JavaScript y el code nativo. Para empezar, configura tu entorno con frameworks específicos para cada plataforma.

Aquí tienes un ejemplo de un Jest unit test para la parte 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 testear el lado nativo, usa XCTest en iOS y JUnit en Android. Aquí un ejemplo para Android:

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

Una vez confirmado que el core del bridge funciona como esperas, pasa a testear los workflows completos del usuario.

Tests completos del plugin

Para asegurar que tu plugin rinda bien en distintos escenarios, testea varias categorías:

Para plugins con funciones complejas, simula escenarios de usuario reales. Por ejemplo, si estás testeando un plugin de DeviceInfo, verifica:

• Uploads exitosos en distintas condiciones de red
• Reporte de progreso preciso
• Uso de memoria durante transferencias de archivos grandes

Testing OTA con Capgo

Las herramientas open-source de Capgo facilitan el despliegue y testeo rápido de actualizaciones. Así es como se usa:

1. Configurar canales de actualización como dev, staging y production.
2. Automatiza despliegues con herramientas de CI/CD.
3. Lanza actualizaciones al instante.
4. Monitoriza el rendimiento y errores desde el dashboard de Capgo.

Para rollouts graduales, Capgo te permite limitar las actualizaciones a un pequeño porcentaje de usuarios. Por ejemplo, puedes lanzar una nueva versión al 25% de los usuarios cada 24 horas:

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

Este enfoque gradual ayuda a detectar problemas pronto, aprovechando el feedback de la comunidad antes del lanzamiento completo.

Proceso de Pull Request

Una vez que hayas probado tus cambios a fondo, sigue estos pasos para enviar tu pull request:

Checklist para enviar el PR

Antes de enviarlo, asegúrate de haber cubierto estos puntos clave:

Guías de la comunidad

Al colaborar, sigue estas buenas prácticas:

• Responde rápido al feedback de los revisores.
• Mantén las discusiones centradas en detalles técnicos.
• Usa la función de sugerencias de GitHub para proponer cambios en code.
• Envía pull requests pequeños y enfocados que resuelvan una sola funcionalidad o issue a la vez.

Para cambios grandes, es mejor crear un issue primero y discutir tu enfoque. El equipo de Capacitor depende de GitHub Actions para los checks automáticos, y todos deben pasar antes de revisar tu pull request.

Guía de integración de Capgo

Si tu plugin incluye live updates, asegúrate de que funcione sin problemas con Capgo antes de enviarlo:

1. Control de versiones
   Usa semantic versioning claro para tu plugin y documenta todos los cambios en el changelog. El sistema de Capgo ayuda a trackear la adopción de versiones en los dispositivos de los usuarios.

2. Integración CI/CD
   Integra Capgo en tu pipeline de CI/CD para automatizar el despliegue de updates.

3. Monitoreo de Updates
   Monitorea la tasa de éxito de los despliegues y asegura el cumplimiento de las reglas de las app stores.

Resumen

Para que tu plugin sea una contribución valiosa, es clave seguir el proceso establecido y cumplir con los estándares de la comunidad. Esto incluye respetar las guías de estilo de Capacitor y testear a fondo tu trabajo.

El checklist del PR subraya la importancia de enviar código de alta calidad. Si tu plugin soporta live updates, integrarlo con Capgo (como mencionamos antes) te permitirá lanzar actualizaciones rápido sin esperar la aprobación de las app stores.

Una vez que tu PR sea mergeado, mantente activo siguiendo los issues y lanzando nuevas versiones. La interacción constante con la comunidad, el mantenimiento regular y estar al día con las actualizaciones de Capacitor garantizarán que tu plugin siga siendo útil y relevante.

Presta atención al feedback de los usuarios y lanza updates según sea necesario. Este esfuerzo continuo ayuda a mantener la calidad del ecosistema y aporta valor a otros desarrolladores.

Continuar desde Capacitor Plugin Contribution Guide

Si estás usando Guía de contribución para plugins de Capacitor para planificar el trabajo del plugin nativo, conéctalo con Directorio de plugins de Capgo para el flujo de trabajo de productos en el Capgo Plugin Directory, Plugins de Capacitor por Capgo para los detalles de implementación en Plugins de Capacitor por Capgo, Añadir o actualizar plugins para los detalles de implementación en Añadir o actualizar plugins, Alternativas a los plugins de Ionic Enterprise para el flujo de trabajo del producto en Alternativas a los plugins de Ionic Enterprise, y Native Builds de Capgo para el flujo de trabajo en Capgo Native Builds.