Guide de contribution aux plugins Capacitor

Les plugins Capacitor connectent les technologies web aux fonctionnalités natives des appareils, permettant le développement d’applications multiplateformes. Ce guide vous aide à :

1. Configurer votre environnement : Des outils comme Node.js, Xcode, et Android Studio sont essentiels.
2. Suivre les normes de code : Utilisez TypeScript, Swift, et Kotlin avec des conventions de nommage cohérentes et une gestion des erreurs.
3. Tester de manière approfondie : Écrivez des tests unitaires pour JavaScript, iOS, et Android afin d’assurer la fiabilité.
4. Documenter clairement : Utilisez JSDoc et des fichiers README pour faciliter l’adoption.
5. Soumettre une demande de tirage : Assurez-vous que le code, les tests et la documentation sont de haute qualité avant de contribuer.

Guide complet sur l’open source - Comment contribuer

Configuration de l’environnement de développement

Créer un environnement de développement adéquat est la clé d’un développement efficace des plugins. Une configuration bien préparée permet une codage, des tests et un déploiement fluides de vos plugins.

Outils et compétences nécessaires

Avant de commencer, assurez-vous d’avoir les outils suivants installés :

Vous devez également être à l’aise avec TypeScript pour le développement web et soit Swift (pour iOS) soit Java/Kotlin (pour Android) pour les tâches de développement natif [1][2].

Configuration du Monorepo

L’écosystème des plugins Capacitor repose sur une structure de monorepo. Cette approche garantit que votre travail est aligné sur les normes de la communauté dès le départ.

1. Forkez et clonez le dépôt
   Commencez par forker le dépôt des plugins Capacitor sur GitHub. Ensuite, clonez votre dépôt forké :

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

2. Installez les dépendances et construisez
   Exécutez la commande suivante pour installer tout ce dont vous avez besoin et construire les plugins :

   npm run build

3. Configurez le contrôle de version
   Utilisez des branches de fonctionnalités pour vos modifications et maintenez votre fork synchronisé avec le dépôt d’origine.

Préparation des plateformes natives

Pour le développement multiplateforme, vous devez configurer les environnements iOS et Android.

Pour iOS :

• Téléchargez Xcode depuis le Mac App Store.

• Installez les outils en ligne de commande en utilisant :

  xcode-select --install

• Installez CocoaPods avec :

  sudo gem install cocoapods

• Créez un compte développeur Apple et obtenez les certificats nécessaires.

• Utilisez SwiftLint (optionnel) pour maintenir la qualité du code.

Pour Android :

• Installez Android Studio avec le dernier SDK et un appareil virtuel.
• Assurez-vous d’avoir un JDK installé.
• Configurez correctement le SDK Android dans Android Studio.

Une fois ces plateformes configurées, vous serez prêt à suivre les pratiques de codage établies et à plonger dans le développement de plugins.

Guide des normes de code

Maintenant que votre environnement de développement est configuré, respectez ces directives pour créer des plugins faciles à maintenir et à utiliser.

Conformité au guide de style

L’écosystème des plugins Capacitor impose des normes de codage strictes utilisant des outils comme ESLint, Prettier, et SwiftLint. Voici un aperçu rapide du formatage requis :

Les plugins devraient utiliser TypeScript pour une meilleure sécurité de type et des fonctionnalités ES6+ comme async/await. De plus, suivez les conventions de codage spécifiques aux plateformes pour Swift (iOS) et Kotlin (Android).

Gestion des erreurs et des types

Une gestion cohérente des erreurs est cruciale pour la compatibilité multiplateforme. Voici un exemple :

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

Pour la sécurité des types :

• Utilisez des interfaces spécifiques adaptées à des cas d’utilisation particuliers.
• Appliquez des types d’union pour les variations spécifiques aux plateformes.
• Implémentez des gardes de type pour valider les types à l’exécution [1].

Documentation de code

Une bonne documentation est essentielle pour rendre votre plugin accessible et facile à utiliser. Respectez ces pratiques :

1. Documentation de l’API : Écrivez des commentaires JSDoc qui fonctionnent avec @capacitor/docgen. Par exemple :

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

2. Structure du README : Incluez des informations essentielles comme les étapes d’installation, les instructions de configuration, les exigences spécifiques aux plateformes, des exemples d’utilisation, et une référence API détaillée.

Une documentation bien écrite garantit que votre plugin est facile à adopter et contribue à la communauté plus large de Capacitor.

sbb-itb-f9944d2

Guide de test de plugin

Tester les plugins Capacitor implique de se concentrer sur quelques domaines critiques pour assurer un bon fonctionnement et une fiabilité.

Tests de pont natif

Le test du pont natif garantit une bonne communication entre JavaScript et le code natif. Pour commencer, configurez votre environnement de test avec des frameworks adaptés à chaque plateforme.

Voici un exemple de test unitaire Jest pour le côté 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);
  });
});

Pour les tests côté natif, utilisez XCTest pour iOS et JUnit pour Android. Voici un exemple pour Android :

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

Une fois que vous avez confirmé que la fonctionnalité du pont de base fonctionne comme prévu, passez aux tests des workflows utilisateur complets.

Tests complets de plugin

Pour garantir que votre plugin fonctionne bien dans différents scénarios, testez diverses catégories :

Pour les plugins avec des fonctionnalités complexes, simulez des scénarios réels d’utilisateur. Par exemple, si vous testez un plugin DeviceInfo, vérifiez :

• Les téléchargements réussis dans différentes conditions de réseau
• Le rapport de progression précis
• L’utilisation de la mémoire pendant les transferts de fichiers volumineux

Tests OTA avec Capgo

Les outils open-source de Capgo facilitent le déploiement et le test des mises à jour rapidement. Voici comment les utiliser :

1. Configurez des canaux de mise à jour comme dev, staging, et production.
2. Automatisez les déploiements avec des outils CI/CD.
3. Poussez les mises à jour instantanément.
4. Surveillez les performances et les problèmes via le tableau de bord Capgo.

Pour les déploiements par phases, Capgo vous permet de limiter les mises à jour à un petit pourcentage d’utilisateurs. Par exemple, vous pouvez déployer une nouvelle version à 25 % des utilisateurs toutes les 24 heures :

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

Cette approche par phases aide à identifier les problèmes tôt en s’appuyant sur les retours de la communauté avant un déploiement complet.

Processus de demande de tirage

Une fois que vous avez soigneusement testé vos modifications, suivez ces étapes pour soumettre votre demande de tirage :

Liste de contrôle de soumission de PR

Avant de soumettre, assurez-vous d’avoir couvert ces domaines clés :

Directives communautaires

Lors de votre collaboration, respectez ces meilleures pratiques :

• Répondez rapidement aux retours des réviseurs.
• Gardez les discussions centrées sur les détails techniques.
• Utilisez la fonction de suggestion de GitHub pour proposer des modifications de code.
• Soumettez des demandes de tirage petites et ciblées qui traitent d’une seule fonctionnalité ou d’un seul problème à la fois.

Pour des modifications plus importantes, il est conseillé de créer un problème d’abord et de discuter de votre approche. L’équipe Capacitor s’appuie sur GitHub Actions pour les vérifications automatisées, et toutes les vérifications doivent réussir avant que votre demande de tirage puisse être examinée.

Guide d’intégration Capgo

Si votre plugin implique des mises à jour en direct, assurez-vous qu’il fonctionne sans problème avec Capgo avant de soumettre :

1. Contrôle de version
   Utilisez un versionnement sémantique clair pour votre plugin, et documentez tous les changements dans le changelog. Le système de Capgo aide à suivre l’adoption des versions sur les appareils des utilisateurs.

2. Intégration CI/CD
   Intégrez Capgo dans votre pipeline CI/CD pour automatiser les déploiements de mises à jour.

3. Surveillance des mises à jour
   Surveillez les taux de succès des déploiements et assurez-vous de respecter les directives des magasins d’applications.

Résumé

Pour apporter une contribution significative avec votre plugin, il est important de suivre le processus établi et de respecter les normes de la communauté. Cela comprend le respect des directives de codage de Capacitor et le test approfondi de votre travail.

La liste de contrôle PR souligne la nécessité de soumissions de haute qualité. Si votre plugin prend en charge des mises à jour en direct, s’intégrer à Capgo (comme mentionné précédemment) peut vous aider à publier rapidement des mises à jour sans attendre l’approbation des magasins d’applications.

Une fois votre PR fusionnée, restez impliqué en suivant les problèmes et en publiant des mises à jour de version. Une interaction régulière avec la communauté, un entretien cohérent, et le suivi des mises à jour de Capacitor garantiront que votre plugin reste utile et pertinent.

Faites attention aux retours des utilisateurs et apportez des mises à jour si nécessaire. Cet effort constant aide à maintenir la qualité globale de l’écosystème et garde votre plugin précieux pour les développeurs.