Capacitor Guide de contribution du plugin

Capacitor Les plugins connectent les technologies web aux fonctionnalités de périphériques natifs, permettant ainsi le développement d'applications cross-plateformes. le développement d'applications cross-plateformes. 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 traitements d'erreurs cohérents.
• Testez soigneusementÉcrire des tests unitaires pour JavaScript, iOS et Android pour garantir la fiabilité.
• Documenter clairementUtiliser JSDoc et des fichiers README pour une adoption facile.
• Soumettre une demande de tirageAssurez-vous d'une qualité élevée code, de tests et de documentation avant de contribuer.

Guide complet sur les logiciels libres - Comment contribuer

Configuration de l'environnement de développement

La création d'un environnement de développement approprié est essentielle au développement efficace de plugins. Un setup bien préparé permet un codage, des tests et une mise en production sans heurts 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 Répertoire Monorepo

Le Capacitor plugins L'écosystème repose sur une structure de répertoire monorepo. Cette approche garantit que votre travail est conforme aux normes de la communauté dès le début.

1. Forker et Cloner le Répertoire
   Commencez par forker le répertoire Capacitor plugins sur GitHub. Ensuite, clonez votre répertoire forké :

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

2. Installer les Dépendances et Construire
   Exécutez la commande suivante pour installer tout ce dont vous avez besoin et construire les plugins :

   npm run build

3. Configurer le Contrôle de Version
   Utilisez des branches de fonctionnalités pour vos modifications et maintenez votre fork synchronisé avec le répertoire upstream.

Préparation des Plates-formes Natives

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

Pour iOS :

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

• Installez les outils de ligne de commande en utilisant :

  xcode-select --install

• Installez CocoaPods avec :

  sudo gem install cocoapods

• Configurez 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 SDK et une machine virtuelle.
• Vérifiez que vous avez 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.

Code Guide des normes

Une fois votre environnement de développement 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 applique des normes de codage strictes à l'aide d'outils comme ESLint, Prettier, et SwiftLint. Voici un aperçu rapide des formats requis :

Les plugins devraient utiliser TypeScript pour une meilleure sécurité des types et des fonctionnalités telles que ES6+ comme : « Swift (iOS) » et « Kotlin (Android) ». En outre, suivez les conventions de codage spécifiques aux plateformes. async/awaitGestion des Erreurs et des Types

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

Pour la sécurité des types :

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

Plugins devraient utiliser TypeScript pour une meilleure sécurité des types et des fonctionnalités telles que ES6+ comme : « Swift (iOS) » et « Kotlin (Android) ». En outre, suivez les conventions de codage spécifiques aux plateformes.

• Utilisez des interfaces ciblées conçues pour des cas d'utilisation spécifiques.
• Appliquez les types de union pour les variations spécifiques aux plateformes.

Code Documentation

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

1. API DocumentationÉ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 READMEIncluez 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

La mise en œuvre de plugins Capacitor implique de se concentrer sur quelques domaines critiques pour s'assurer d'une fonctionnalité et d'une fiabilité fluides.

Tests de la passerelle native

Les tests de la passerelle native s'assurent de la communication appropriée entre JavaScript et code. Pour commencer, configurez votre environnement de test avec des frameworks adaptés à chaque plateforme.

Voici un exemple d'un Jest test unitaire 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 base de la passerelle fonctionne comme prévu, passez à la mise en œuvre de tests de workflows complets.

Tests de plugins complets

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

Pour les plugins avec des fonctionnalités complexes, simulez des scénarios de l'usage réel. Par exemple, si vous testez un plugin DeviceInfo, vérifiez :

• Téléchargements réussis sous différentes conditions de réseau
• Rapports de progression précis
• Utilisation de la mémoire pendant les transferts de fichiers importants

Test de mise à jour OTA avec __CAPGO_KEEP_0__ Test de mise à jour OTA avec Capgo

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

1. Configurer canaux d'actualisation comme le dev, le stade et la production.
2. Automatiser les déploiements avec les outils CI/CD.
3. Envoyer des actualisations instantanément.
4. Surveiller les performances et les problèmes via le Capgo tableau de bord.

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

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

Cette approche étalée aide à identifier les problèmes tôt en exploitant les commentaires de la communauté avant une mise en production complète.

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 vérification de soumission de PR

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

Règles 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.
• Utilisez la fonctionnalité de proposition de GitHub pour proposer code modifications.
• Soumettez des demandes de modification petites et centré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 avant et discuter de votre approche. L'équipe de Capacitor se fie sur les Actions de GitHub pour les contrôles automatisés, et toutes les contrôles doivent passer avant que votre demande de modification 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 le soumettre :

1. Gestion de version
   Utilisez une versionnement semantique claire 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 des utilisateurs.

2. Intégration CI/CD
   Intégrez Capgo dans votre pipeline CI/CD pour automatiser les déploiements d'actualisation.

3. Mise à jour de la surveillance
   Surveillez les taux de réussite des déploiements et assurez-vous de respecter les lignes directrices des magasins d'applications.

Résumé

Pour faire une contribution significative avec votre plugin, il est important de suivre le processus établi et de respecter les normes de la communauté. Cela inclut la tenue aux lignes directrices de codage de Capacitor et la vérification minutieuse de votre travail.

La liste de vérification du 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.

Une fois votre PR fusionné, restez impliqué en suivant les problèmes et en libérant les mises à jour de version. L'interaction régulière avec la communauté, la maintenance constante et la mise à jour avec les mises à jour de Capacitor assureront que votre plugin reste utile et pertinent.

Faites attention aux commentaires des utilisateurs et mettez à jour en conséquence. Cette démarche continue aide à maintenir la qualité globale de l'écosystème et rend votre plugin précieux pour les développeurs.