Guide de contribution aux plugins Capacitor

Capacitor les plugins connectent les technologies web aux fonctionnalités natives de l'appareil, permettant le développement d'applications multiplateformes. Ce guide vous aide à :

• Configurer votre environnement: Des outils comme Node.js, Xcode, et Android Studio sont essentiels.
• Respectez les standards Code: Utilisez TypeScript, Swift, et Kotlin avec des conventions de nommage et une gestion d'erreurs cohérentes.
• Testez minutieusement: Écrivez des tests unitaires pour JavaScript, iOS et Android pour garantir la fiabilité.
• Documentez clairement: Utilisez JSDoc et des fichiers README pour faciliter l'adoption.
• Soumettez une Pull Request: Assurez une code de haute qualité, ainsi que des tests et une documentation avant de contribuer.

Guide complet de l'open source : comment contribuer

Configuration de l'environnement de développement

Créer un environnement de développement adéquat est essentiel pour développer des plugins efficacement. Une configuration bien préparée permet de coder, tester et déployer vos plugins en toute fluidité.

Outils et skills nécessaires

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

Vous devriez également être à l'aise avec TypeScript pour le développement web, ainsi qu'avec Swift (pour iOS) ou Java/Kotlin (pour Android) pour les tâches de développement natif [1][2].

Configuration du monorepo

Le Plugins Capacitor l'écosystème repose sur une structure monorepo. Cette approche garantit que votre travail respecte les standards de la communauté dès le départ.

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

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

2. Installer les dépendances et builder
   Exécutez la commande suivante pour installer tout le nécessaire et builder les plugins :

   npm run build

3. Configurer le contrôle de version
   Utilisez des branches de fonctionnalités pour vos changements et gardez votre fork synchronisé avec le dépôt upstream.

Préparer les plateformes natives

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

Pour iOS :

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

• Installez les outils en ligne de commande avec :

  xcode-select --install

• Installez CocoaPods avec :

  sudo gem install cocoapods

• Configurez un compte Apple Developer et les certificats nécessaires.

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

Pour Android :

• Installez Android Studio avec la dernière version de 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 bonnes pratiques de code et à vous lancer dans le développement de plugins.

Guide des standards Code

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

Respect du guide de style

Le l'écosystème de plugins Capacitor impose des standards de code stricts via des outils comme ESLint, Prettier, et SwiftLint. Voici un aperçu rapide du formatage requis :

Plugins should use TypeScript for better type safety and ES6+ features like async/await. De plus, respectez les conventions de code 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é du typage :

• Utilisez des interfaces ciblées et adaptées à des cas d'usage précis.
• Appliquez des types d'union pour les variations spécifiques aux plateformes.

Documentation Code

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

1. Documentation API: Rédigez des commentaires JSDoc compatibles 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 les informations essentielles comme les étapes d'installation, les instructions de configuration, les prérequis par plateforme, des exemples d'utilisation et une référence API détaillée.

Une documentation bien écrite garantit l'adoption de votre plugin et contribue à la communauté Capacitor.

sbb-itb-f9944d2

Guide de test de plugin

Tester les plugins Capacitor nécessite de se concentrer sur quelques domaines critiques pour garantir une fonctionnalité fluide et fiable.

Tests du bridge natif

Les tests du bridge natif garantissent une communication correcte entre JavaScript et code natif. Pour commencer, configurez votre environnement de test avec des frameworks adaptés à chaque plateforme.

Voici un exemple de Jest test unitaire pour la partie 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 tester la partie native, 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é de base du bridge fonctionne comme prévu, passez au test des workflows utilisateurs complets.

Tests complets du plugin

Pour garantir que votre plugin est performant dans différents scénarios, testez plusieurs catégories :

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

• Le succès des uploads selon les conditions réseau
• La précision du rapport de progression
• Memory usage during large file transfers

Tests OTA avec Capgo

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

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

Pour les déploiements progressifs, Capgo vous permet de limiter les mises à jour à un petit pourcentage d'utilisateurs. Par exemple, vous pouvez déployer une nouvelle version auprès de 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 progressive permet d'identifier les problèmes rapidement en s'appuyant sur les retours de la communauté avant une release complète.

Processus de pull request

Une fois que vous avez testé vos changements en profondeur, suivez ces étapes pour soumettre votre pull request :

Checklist de soumission de PR

Avant de soumettre, assurez-vous d'avoir couvert ces points clés :

Directives de la communauté

Pour collaborer, respectez ces bonnes pratiques :

• Répondez rapidement aux retours des relecteurs.
• Gardez les discussions centrées sur les détails techniques.
• Use GitHub’s suggestion feature to propose code changes.
• Soumettez des pull requests courtes et ciblées qui traitent une seule fonctionnalité ou un seul problème à la fois.

Pour les changements plus importants, mieux vaut créer d'abord une issue pour discuter de votre approche. L'équipe Capacitor s'appuie sur les GitHub Actions pour les vérifications automatiques, et toutes les vérifications doivent passer avant que votre pull request puisse être relue.

Guide d'intégration Capgo

Si votre plugin implique des live updates, assurez-vous qu'il fonctionne parfaitement avec Capgo avant de le soumettre :

1. Gestion des versions
   Utilisez un versionnage 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 à votre pipeline CI/CD pour automatiser le déploiement des mises à jour.

3. Suivi des mises à jour
   Surveillez les taux de réussite des déploiements et assurez la conformité avec les directives des stores.

Résumé

Pour apporter une contribution significative avec votre plugin, il est important de suivre le processus établi et de respecter les standards de la communauté. Cela inclut le respect des guidelines de code de Capacitor et des tests approfondis de votre travail.

La checklist de la PR souligne la nécessité de soumettre du code de haute qualité. Si votre plugin supporte les live updates, l'intégration avec Capgo (comme mentionné plus haut) peut vous aider à publier des mises à jour rapidement sans attendre l'approbation des stores.

Une fois votre PR fusionnée, restez impliqué en suivant les issues et en publiant des mises à jour de version. Une interaction régulière avec la communauté, une maintenance constante et une veille sur les mises à jour de Capacitor permettront à votre plugin de rester utile et pertinent.

Soyez attentif aux retours des utilisateurs et effectuez des mises à jour si nécessaire. Cet effort continu aide à maintenir la qualité globale de l'écosystème et la valeur de votre plugin pour les développeurs.

Continuer depuis le guide de contribution de plugin Capacitor

Si vous utilisez Guide de contribution aux plugins Capacitor pour planifier le travail sur un plugin natif, connectez-l’à Répertoire des plugins Capgo pour le workflow produit dans le répertoire des plugins Capgo, Plugins Capacitor par Capgo pour les détails d'implémentation dans les plugins Capacitor par Capgo, Ajouter ou mettre à jour des plugins pour les détails d'implémentation dans Adding or Updating Plugins, Alternatives aux plugins Ionic Enterprise pour le workflow produit dans les alternatives aux plugins Ionic Enterprise, et Capgo Native Build pour le workflow produit dans les Capgo Native Builds.