Guide de contribution de plugin Capacitor

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

• Configurer votre environnement : Les outils comme Node.js, Xcode, et Android Studio sont essentiels.
• Suivez les Code Standards: Utilisez TypeScript, Swift, et Kotlin avec des conventions de nommage et des gestionnaires d'erreurs cohérents.
• Testez Soigneusement: Écrivez des tests unitaires pour JavaScript, iOS et Android pour garantir la fiabilité.
• Documentez de Manière Claire: Utilisez JSDoc et des fichiers README pour une adoption facile.
• Soumettez une Demande de TirageAssurez une qualité élevée des code, des tests et de la documentation avant de contribuer.

Guide complet pour les logiciels open source - Comment contribuer

Configuration de l'environnement de développement

Créer un environnement de développement approprié est essentiel pour une création de plugin efficace. Un setup bien préparé facilite le codage, les tests et la mise en production de vos plugins.

Outils et compétences dont vous aurez besoin

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

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

Configuration de la Monoréférence

La Capacitor plugins Le système repose sur une structure de monorepo. Cela garantit que votre travail est conforme aux normes de la communauté dès le départ.

1. Faites un fork et clonez le dépôt.
   Commencez par faire un fork du dépôt de 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 la gestion de version.
   Utilisez des branches de fonctionnalités pour vos modifications et gardez votre fork synchronisé avec le dépôt upstream.

Préparez les plateformes natives.

Pour le développement cross-plateforme, vous aurez besoin de configurer les environnements iOS et Android.

Pour iOS :

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

• Install command-line tools using:

  xcode-select --install

• Installez CocoaPods avec :

  sudo gem install cocoapods

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

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

Pour Android :

• Installez Android Studio ainsi que 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 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é, suivez ces lignes directrices pour créer des plugins faciles à maintenir et à utiliser.

Conformité au Guide de style

Le Capacitor écosystème de plugins exige des normes de codage strictes à l'aide d'outils comme ESLint, Prettier, et SwiftLint. Voici un aperçu rapide des formats requis :

Plugins devraient utiliser TypeScript pour une meilleure sécurité des types et des fonctionnalités ES6+. 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é cross-plateforme. 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 ciblées pour des cas d'utilisation spécifiques.
• Apply union types for platform-specific variations.

Documentation de Code

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

1. Documentation 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 détaillée API.

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

sbb-itb-f9944d2

Guide de test de plugin

Testez les plugins Capacitor en vous concentrant sur quelques domaines clés pour garantir une fonctionnalité fluide et fiable.

Tests de pont natif

Les tests de pont natif assurent une communication appropriée entre JavaScript et code. Pour commencer, configurez votre environnement de test avec des frameworks conçus pour chaque plateforme.

Ici est un exemple de Jest test unit 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 tester du 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é de pont de base fonctionne comme prévu, passez à la mise en œuvre de workflows utilisateur complets.

Tests complets du Plugin

Pour vous assurer que votre plugin fonctionne bien dans différents scénarios, testez différentes catégories :

Simulez des scénarios de l'utilisateur dans le monde réel pour les plugins avec des fonctionnalités complexes. Par exemple, si vous testez un plugin DeviceInfo, vérifiez :

• Chargements réussis sous différentes conditions de réseau
• Rapports de progression précis
• Memory usage during large file transfers

Tests OTA avec Capgo

Capgo’s outils open-source rendent facile la mise en œuvre et le test des mises à jour rapidement. Voici comment l'utiliser :

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

Pour les déploiements étalés, Capgo vous permet de limiter les mises à jour à une petite fraction d'utilisateurs. Par exemple, vous pouvez déployer une nouvelle version à 25 % d'utilisateurs tous les 24 heures :

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

Cette approche progressive aide à identifier les problèmes tôt en exploitant les retours de la communauté avant une mise à jour complète.

Procédure de Demande de Tirage

Une fois vos modifications testées, suivez ces étapes pour soumettre votre demande de tirage.

Liste de vérification pour soumission de PR

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

Lignes directrices de la communauté

Lors de la collaboration, suivez ces meilleures pratiques :

• Répondez rapidement aux commentaires des réviseurs.
• Gardez les discussions centrées sur les détails techniques.
• Use GitHub’s suggestion feature to propose code changes.
• Soumettez des demandes de tirage de petite taille, axées sur une fonctionnalité ou un problème à la fois.

Pour des modifications plus importantes, il est une bonne idée de créer un problème en premier et de discuter de votre approche. L'équipe de Capacitor se fonde sur les GitHub Actions pour les vérifications automatiques, et toutes les vérifications doivent passer avant que votre demande de tirage ne puisse être examinée.

Guide d'intégration de Capgo

Si votre plugin implique des mises à jour en temps réel, assurez-vous qu'il fonctionne de manière fluide avec Capgo avant de soumettre :

1. Contrôle de version
   Utilisez une versionnement semantique clair pour votre plugin, et documentez toutes les modifications dans le changelog. Le système de Capgo aide à suivre l'adoption des versions sur les appareils utilisateur.

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

3. Suivi des mises à jour
   Suivez les taux de réussite de déploiement et assurez-vous de respecter les directives des magasins d'applications.

Résumé

To apporter une contribution significative avec votre plugin, il est important de suivre le processus établi et de respecter les normes de la communauté. Cela inclut le respect des lignes directrices de codage de Capacitor et une vérification approfondie de votre travail.

Le checklist PR met en évidence la nécessité de soumissions de haute qualité. Si votre plugin prend en charge les mises à jour en direct, l'intégration avec Capgo (comme mentionné précédemment) peut vous aider à libérer des mises à jour rapidement sans attendre les approbations des magasins d'applications.

Restez impliqué en suivant les problèmes et en publiant des mises à jour de versions régulières. Une interaction constante avec la communauté, une maintenance cohérente, et keeping up with Capacitor updates garantira que votre plugin reste utile et pertinent.

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.

Continuez de Capacitor Guide de contribution de plugin

le guide de contribution de __CAPGO_KEEP_0__ Plugin Guide de contribution de plugin Capacitor le répertoire de plugin de __CAPGO_KEEP_0__ Répertoire de plugins Capgo pour le flux de travail du produit dans le Répertoire de Plugin Capgo Capacitor Plugins by Capgo pour le détail d'implémentation en Capacitor Plugins par Capgo Ajouter ou Mettre à Jour les Plugins pour le détail d'implémentation en Ajouter ou Mettre à Jour les Plugins Alternatives aux Plugins Entreprise Ionic pour le flux de travail produit en Alternatives aux Plugins Entreprise Ionic, et Capgo Bâtiments Natives pour le flux de travail produit en Capgo Bâtiments Natives.