Guía de contribución de plugins Capacitor

Capacitor conectar tecnologías web con características de dispositivos nativos, lo que permite desarrollo de aplicaciones de múltiples plataformas. Esta guía te ayudará:

• Configurar tu Entorno: Herramientas como Node.js, Xcode, y Android Studio son fundamentales.
• Siga los Code estándares: 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.
• Envíe una solicitud de extracciónAsegúrese de tener una alta calidad de code, 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 sentirse cómodo con TypeScript para el desarrollo web y, por lo tanto, con Swift (para iOS) o Java/Kotlin (para Android) para tareas de desarrollo nativo [1][2].

Configuración de la monorepo

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

1. Fork y clone el repositorio
   Comienza forkeando el repositorio de plugins Capacitor 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 Versiones
   Utiliza ramas de características para tus cambios y mantén tu fork sincronizado con el repositorio upstream.

Preparar Plataformas Nativas

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

Para iOS:

• Descarga Xcode desde la Tienda de Mac.

• Install command-line tools using:

  xcode-select --install

• Instale CocoaPods con:

  sudo gem install cocoapods

• Configura una 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 versión de SDK y una máquina virtual.
• Asegúrese de tener instalado un JDK.
• Configure correctamente el archivo SDK de Android dentro de Android Studio.

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

Code Standards Guide

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

Compliance con la Guía de Estilo

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

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

Manejo de errores consistente es crucial para la compatibilidad entre plataformas. Aquí tienes 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. Documentación de JSDoc: Incluye información esencial como instrucciones de instalación, configuración, requisitos específicos de plataforma, ejemplos de uso y una referencia detallada de 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

Las pruebas de 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, configura tu entorno de prueba con marcos adaptados a cada plataforma.

Aquí tienes 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 confirmado que la funcionalidad de la puente básica funciona como se espera, proceda 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 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 de CI/CD.
3. Envíe actualizaciones de manera instantánea.
4. Monitor performance and issues a través de la panel de control de Capgo.

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"
  }
}

Este enfoque en fases ayuda a identificar problemas temprano aprovechando la retroalimentación de la comunidad antes de una versió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 Envío de PR

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

Directrices de la comunidad

Cuando colabores, sigue estas mejores prácticas:

• Responder rápidamente a los comentarios del revisor.
• Mantenga las discusiones enfocadas en detalles técnicos.
• Utilice la función de sugerencia 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 su enfoque. El equipo de Capacitor depende de GitHub Acciones 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

Asegúrese de que su plugin 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. El sistema de Capgo ayuda a rastrear la adopción de versiones en dispositivos de los usuarios.

2. Integración CI/CD
   Integra Capgo en tu pipeline de CI/CD para automatizar los despliegues de actualizaciones.

3. Actualización de seguimiento
   Integre __CAPGO_KEEP_0__ en su pipeline de CI/CD para automatizar las actualizaciones de despliegue.

Summary

Hacer una contribución significativa con tu plugin requiere 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 (como se mencionó anteriormente) puede ayudarte a publicar actualizaciones rápidamente sin tener que esperar aprobaciones de la tienda de aplicaciones.

Una vez que se mergea tu PR, sigue involucrado siguiendo los problemas y actualizando las versiones. La interacción regular con la comunidad, el mantenimiento consistente y keeping up with Capacitor updates asegurará que su plugin siga siendo útil y relevante.

Pay attention to user feedback and make updates as needed. This ongoing effort helps maintain the overall quality of the ecosystem and keeps your plugin valuable for developers.

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

la Guía de Contribución de Plugins de __CAPGO_KEEP_0__ Guía de Contribución de Plugins de Capacitor el Directorio de Plugins de __CAPGO_KEEP_0__ para el flujo de trabajo del producto en el Directorio de Plugins de Capgo para el flujo de trabajo del producto en el directorio de plugins Capgo Capacitor Plugins by Capgo para los detalles 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 Ionic Enterprise para el flujo de trabajo del producto en Ionic Enterprise Plugin Alternatives, y Capgo Compilaciones Nativas para el flujo de trabajo del producto en Capgo Compilaciones Nativas.