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:

• 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 las convenciones de nombres y manejo de errores consistentes.
• Prueba exhaustivamente: Escribe pruebas unitarias para JavaScript, iOS y Android para garantizar la confiabilidad.
• Documenta claramente: Utiliza JSDoc y archivos README para una adopción fácil.
• Hacer una solicitud de extracción: Asegúrate de que tu 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 tus plugins.

Herramientas y habilidades que necesitarás

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

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

Configuración de la carpeta monorepo

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

1. Crear una rama y clonar el repositorio
   Comienza creando una rama del repositorio de Capacitor plugins en GitHub. Luego, clona tu repositorio bifurcado:

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

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

• 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 code calidad.

Para Android:

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

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

Code Guía de Estándares

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

Cumplimiento de la Guía de Estilo

La Capacitor ecosistema de plugins impone estándares de codificación estrictos 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, sigan las convenciones de codificación específicas de la plataforma para Swift (iOS) y Kotlin (Android).

Error and Type Management

La gestión de errores y tipos 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 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, instrucciones de 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 más amplia Capacitor.

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 puente nativo garantiza una comunicación adecuada entre JavaScript y code. Para empezar, configura tu entorno de prueba con marcos adaptados a cada plataforma.

Aquí tienes un ejemplo de Jest una 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, utiliza XCTest para iOS y JUnit para Android. A continuación, tienes un ejemplo para Android:

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

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

Pruebas de Plugin Completas

Asegúrese de que su plugin funcione bien en diferentes escenarios, probando varias categorías:

Para plugins con características complejas, simule escenarios 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 actualización OTA con Capgo

Las herramientas de código abierto de Capgo 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. Automatizar despliegues con herramientas CI/CD.
3. Enviar actualizaciones de manera instantánea.
4. Monitorear rendimiento e issues a través del Capgo dashboard.

Para rollouts en fases, Capgo te permite limitar 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"
  }
}

Este enfoque 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:

Directrices de la comunidad

Cuando colabores, sigue estas mejores prácticas:

• Respónde rápidamente a los comentarios de los revisores.
• Mantén 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 una característica o problema a la vez.

Para cambios más grandes, es una buena idea crear un problema primero y discutir tu enfoque. El equipo de Capacitor depende de GitHub Actions para verificaciones automatizadas, y todas las verificaciones deben pasar antes de que tu 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 enviarlo:

1. Control de versiones
   Utilice una versión semántica clara para su plugin y documente todos los cambios en el registro de cambios. Capgo’s sistema ayuda a rastrear la adopción de versiones en dispositivos de 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 exhaustivamente su trabajo.

La lista de verificación de PR destaca la necesidad de presentaciones de alta calidad. Si su plugin admite actualizaciones en vivo, integrar con Capgo (tal como se mencionó anteriormente) puede ayudarlo a publicar 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 publicando actualizaciones de versiones. La interacción regular con la comunidad, el mantenimiento consistente y el mantenimiento de actualizaciones de Capacitor asegurará que su plugin siga siendo útil y relevante.

Atiéndase a los comentarios del usuario 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 Plugin Capacitor

Si estás utilizando Capacitor Guía de Contribución de Plugin para planificar el trabajo de plugin nativo, conecta con Capgo Directorio de Plugin para el flujo de trabajo del producto en Capgo Directorio de Plugin, Capacitor Plugins por Capgo para los detalles de implementación en Capacitor Plugins 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 Ionic Enterprise Plugin Alternatives, y Capgo Construcción Nativa para el flujo de trabajo del producto en Capgo Construcción Nativa.