Guida alla contribuzione ai plugin Capacitor

Capacitor i plugin collegano le tecnologie web alle funzionalità native del dispositivo, permettendo lo sviluppo di app cross-platform. Questa guida ti aiuterà a:

• Configurare l'ambiente di sviluppo: Tool come Node.js, Xcode, e Android Studio sono essenziali.
• Segui gli standard di Code: Usa TypeScript, Swift, e Kotlin con naming convention e gestione degli errori coerenti.
• Testa a fondo: Scrivi unit test per JavaScript, iOS e Android per garantire l'affidabilità.
• Documenta chiaramente: Usa JSDoc e file README per facilitare l'adozione.
• Invia una Pull RequestAssicurati che code, test e documentazione siano di alta qualità prima di contribuire.

Guida completa all'Open Source: come contribuire

Configurazione dell'ambiente di sviluppo

Creare un ambiente di sviluppo adeguato è fondamentale per sviluppare plugin in modo efficiente. Un setup ben preparato permette di scrivere, testare e distribuire i plugin senza intoppi.

Strumenti e competenze necessarie

Prima di iniziare, assicurati di avere installato i seguenti strumenti:

Dovresti inoltre avere familiarità con TypeScript per lo sviluppo web e con Swift (per iOS) o Java/Kotlin (per Android) per i task di sviluppo nativo [1][2].

Configurazione del Monorepo

L'oggetto plugin Capacitor l'ecosistema si basa su una struttura monorepo. Questo approccio assicura che il tuo lavoro sia in linea con gli standard della community fin dall'inizio.

1. Fork e Clone del Repository
   Inizia facendo il fork del repository dei plugin Capacitor su GitHub. Poi, clona il tuo repository:

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

2. Installazione Dipendenze e Build
   Esegui il seguente comando per installare tutto il necessario e buildare i plugin:

   npm run build

3. Configurazione Version Control
   Usa i feature branch per le tue modifiche e mantieni il tuo fork sincronizzato con il repository upstream.

Preparazione delle piattaforme Native

Per lo sviluppo cross-platform, dovrai configurare gli ambienti iOS e Android.

Per iOS:

• Scarica Xcode dal Mac App Store.

• Installa i command-line tools usando:

  xcode-select --install

• Installa CocoaPods con:

  sudo gem install cocoapods

• Configura un account Apple Developer e i certificati necessari.

• Usa SwiftLint (opzionale) per mantenere la qualità di code.

Per Android:

• Installa Android Studio insieme all'ultima versione di SDK e un dispositivo virtuale.
• Assicurati di avere un JDK installato.
• Configura correttamente l'SDK di Android in Android Studio.

Una volta configurate queste piattaforme, sarai pronto a seguire le best practice e a iniziare lo sviluppo dei plugin.

Guida agli standard Code

Ora che il tuo ambiente di sviluppo è pronto, segui queste linee guida per creare plugin facili da mantenere e usare.

Conformità alla Style Guide

L'oggetto ecosistema di plugin Capacitor impone standard di coding rigorosi tramite tool come ESLint, Prettier, e SwiftLint. Ecco una panoramica della formattazione richiesta:

I plugin dovrebbero usare TypeScript per una migliore type safety e le feature ES6+, come async/await. Inoltre, segui le convenzioni di coding specifiche per Swift (iOS) e Kotlin (Android).

Gestione di Errori e Tipi

Una gestione coerente degli errori è fondamentale per la compatibilità cross-platform. Ecco un esempio:

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

Per la type safety:

• Usa interfacce mirate per casi d'uso specifici.
• Applica gli union types per le variazioni di piattaforma.

Documentazione Code

Una buona documentazione è fondamentale per rendere il tuo plugin accessibile e facile da usare. Segui queste pratiche:

1. Documentazione API: Scrivi commenti JSDoc compatibili con @capacitor/docgen. Per esempio:

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

2. Struttura del README: Includi informazioni essenziali come i passaggi di installazione, le istruzioni di configurazione, i requisiti specifici per piattaforma, esempi d'uso e un riferimento dettagliato a API.

Una documentazione ben scritta facilita l'adozione del tuo plugin e contribuisce alla vasta community Capacitor.

sbb-itb-f9944d2

Guida al testing dei plugin

Il testing dei plugin Capacitor richiede attenzione su alcune aree critiche per garantire funzionalità e affidabilità.

Test del Native Bridge

Il testing del bridge nativo assicura la corretta comunicazione tra JavaScript e code nativo. Per iniziare, configura l'ambiente di test con framework specifici per ogni piattaforma.

Ecco un esempio di Jest unit test per la parte 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);
  });
});

Per il testing lato nativo, usa XCTest per iOS e JUnit per Android. Ecco un esempio per Android:

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

Una volta confermato che il core del bridge funzioni correttamente, passa al testing dei workflow completi dell'utente.

Test completi del plugin

Per assicurarti che il tuo plugin funzioni bene in diversi scenari, testa varie categorie:

Per plugin con feature complesse, simula scenari d'uso reali. Ad esempio, se testi un plugin DeviceInfo, verifica:

• Upload riusciti con diverse condizioni di rete
• Reporting accurato del progresso
• Uso della memoria durante il trasferimento di file grandi

Test OTA con Capgo

Gli strumenti open-source di Capgo rendono facile il deploy e il testing rapido degli update. Ecco come usarli:

1. Configura canali di aggiornamento come dev, staging e production.
2. Automatizza i deployment con strumenti CI/CD.
3. Invia gli update istantaneamente.
4. Monitora performance e bug tramite il dashboard Capgo.

Per i rollout graduali, Capgo ti permette di limitare gli update a una piccola percentuale di utenti. Ad esempio, puoi rilasciare una nuova versione al 25% degli utenti ogni 24 ore:

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

Questo approccio graduale aiuta a identificare i problemi in anticipo, sfruttando il feedback della community prima del rilascio completo.

Processo della Pull Request

Dopo aver testato accuratamente le tue modifiche, segui questi passaggi per inviare la pull request:

Checklist per l'invio della PR

Prima di inviare, assicurati di aver coperto questi punti chiave:

Linee guida della community

Quando collabori, segui queste best practice:

• Rispondi rapidamente ai feedback dei reviewer.
• Mantieni le discussioni focalizzate sui dettagli tecnici.
• Usa la funzione di suggerimento di GitHub per proporre modifiche a code.
• Invia pull request piccole e mirate che risolvano una singola feature o issue alla volta.

Per modifiche più ampie, conviene prima aprire un'issue e discutere l'approccio. Il team di Capacitor si affida a GitHub Actions per i controlli automatizzati, e tutti i test devono passare prima che la tua pull request venga revisionata.

Guida all'integrazione Capgo

Se il tuo plugin include Live Update, assicurati che funzioni perfettamente con Capgo prima di inviarlo:

1. Controllo di versione
   Usa un semantic versioning chiaro per il tuo plugin e documenta ogni modifica nel changelog. Il sistema di Capgo aiuta a monitorare l'adozione delle versioni sui dispositivi degli utenti.

2. Integrazione CI/CD
   Integra Capgo nella tua pipeline CI/CD per automatizzare il deployment degli update.

3. Monitoraggio Update
   Monitora il tasso di successo dei deployment e garantisci la conformità alle linee guida degli app store.

Riassunto

Per dare un contributo significativo con il tuo plugin, è importante seguire il processo stabilito e rispettare gli standard della community. Ciò include l'aderenza alle coding guidelines di Capacitor e un test approfondito del tuo lavoro.

La checklist della PR sottolinea la necessità di invii di alta qualità. Se il tuo plugin supporta i live updates, l'integrazione con Capgo (come menzionato prima) può aiutarti a rilasciare update rapidamente senza attendere le approvazioni degli app store.

Una volta approvata la PR, resta attivo seguendo le issue e rilasciando nuovi aggiornamenti di versione. L'interazione regolare con la community, una manutenzione costante e tenersi aggiornati su Capacitor garantiranno che il tuo plugin rimanga utile e rilevante.

Presta attenzione al feedback degli utenti e rilascia update quando necessario. Questo impegno continuo aiuta a mantenere la qualità dell'ecosistema e rende il tuo plugin prezioso per gli sviluppatori.

Torna alla Capacitor Plugin Contribution Guide

Se stai usando Guida alla contribuzione ai plugin per Capacitor per pianificare il lavoro sui plugin nativi, collegalo a Directory dei plugin Capgo per il workflow del prodotto nella Directory dei plugin Capgo, Plugin Capacitor di Capgo per i dettagli di implementazione in Capacitor Plugins by Capgo, Aggiungere o aggiornare i plugin per i dettagli di implementazione in Adding or Updating Plugins, Alternative ai plugin Ionic Enterprise per il workflow del prodotto in Ionic Enterprise Plugin Alternatives, e Capgo Native Build per il workflow del prodotto in Capgo Native Builds.