Capacitor Guida alla Contribuzione dei Plugin

Capacitor i plugin connettono le tecnologie web con le funzionalità di dispositivo nativo, consentendo lo sviluppo di applicazioni cross-platform. Questa guida ti aiuta:

• Configura il tuo ambiente: Strumenti come Node.js, Xcode, e Android Studio sono essenziali.
• Segui Code Standards: Utilizza TypeScript, Swift, e Kotlin con gli convenzioni di denominazione coerenti e il trattamento degli errori.
• Testa Accuratamente: Scrivi test unitari per JavaScript, iOS e Android per garantire la affidabilità.
• Documenta Chiaramente: Utilizza JSDoc e file README per un'adozione facile.
• Invia una Richiesta di Modifica: Assicurati di una qualità alta code, testing e documentazione prima di contribuire.

Guida Completa per Open Source - Come Contribuire

Configurazione dell'ambiente di sviluppo

La configurazione di un ambiente di sviluppo appropriato è fondamentale per lo sviluppo efficiente dei plugin. Un setup ben preparato consente una codifica, un testing e una distribuzione dei plugin fluidi.

Strumenti e Competenze da Utilizzare

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

Dovresti anche essere a tuo agio con TypeScript per lo sviluppo web e con Swift (per iOS) o Java/Kotlin (per Android) per le attività di sviluppo nativo [1][2].

Impostazione del Monorepo

Il Capacitor plugin L'ecosistema si basa su una struttura di monorepo. Questo approccio garantisce che il tuo lavoro si allinei alle norme della community fin dall'inizio

1. Fork e Clona il Repository
   Inizia a forking il repository dei Capacitor plugin su GitHub. Poi, clona il tuo repository forkato:

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

2. Installa le Dipendenze e Costruisci
   Esegui il seguente comando per installare tutto ciò di cui hai bisogno e costruire i plugin:

   npm run build

3. Configura il Controllo delle Versioni
   Utilizza rami di feature per le tue modifiche e mantieni sincronizzato il tuo fork con il repository upstream.

Preparazione delle Piattaforme Native

Per lo sviluppo cross-platform, avrai bisogno di configurare sia l'ambiente iOS che Android.

Per iOS:

• Scarica Xcode dal Mac App Store.

• Installa gli strumenti di riga di comando con:

  xcode-select --install

• Installa CocoaPods con:

  sudo gem install cocoapods

• Configura un account di sviluppatore Apple e i certificati necessari.

• Utilizza SwiftLint (facoltativo) per mantenere la code qualità.

Per Android:

• Installa Android Studio insieme alla versione più recente SDK e a un dispositivo virtuale.
• Assicurati di avere installato un JDK.
• Configura correttamente l'SDK Android all'interno di Android Studio.

Una volta configurati questi piattaforme, sarai pronto a seguire le pratiche di programmazione consolidate e a immergerti nel sviluppo di plugin.

Guida per gli standard di Code

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

Compliance dello Style Guide

La ecosistema dei plugin Capacitor impone standard di codifica rigorosi utilizzando strumenti come ESLint, Prettier, e SwiftLint. Ecco un breve riassunto dei requisiti di formattazione:

I plugin dovrebbero utilizzare TypeScript per una maggiore sicurezza dei tipi e le funzionalità di ES6+ come async/await. Inoltre, segui le convenzioni di codifica specifiche per la piattaforma per Swift (iOS) e Kotlin (Android).

Errori e Gestione dei Tipi

La gestione degli errori coerente è 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 sicurezza dei tipi:

• Utilizza interfacce focalizzate su casi d'uso specifici.
• Applica tipi di unione per variazioni specifiche delle piattaforme.

Code Documentazione

La documentazione di alta qualità è essenziale per rendere il tuo plugin accessibile e facile da utilizzare. Segui queste pratiche:

1. API Documentazione: Scrivi commenti JSDoc che funzionano con @capacitor/docgen. Ad 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, le richieste specifiche delle piattaforme, gli esempi di utilizzo e una dettagliata API reference.

Una documentazione ben scritta assicura che il tuo plugin sia facile da adottare e contribuisce alla comunità più ampia Capacitor.

sbb-itb-f9944d2

Guida per il testing dei plugin

Il testing dei plugin Capacitor prevede di concentrarsi su alcune aree critiche per garantire una funzionalità liscia e una affidabilità.

Test del ponte nativo

Il testing del ponte nativo assicura una comunicazione corretta tra JavaScript e code. Per iniziare, configura il tuo ambiente di testing con framework adatti a ogni piattaforma.

Ecco un esempio di Jest test di unità per il lato 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 sul lato nativo, utilizza 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 confermata la funzionalità del ponte di base funziona come previsto, passa al testing di flussi di lavoro completi dell'utente.

Test dei plugin completi

To assicurarsi che il tuo plugin funzioni bene in diversi scenari, testa varie categorie:

Per i plugin con funzionalità complesse, simulare scenari realistici di utilizzo da parte degli utenti. Ad esempio, se si sta testando un plugin DeviceInfo, verificare:

• Caricamenti riusciti in diverse condizioni di rete
• Rapporto di avanzamento preciso
• Utilizzo della memoria durante i trasferimenti di file di grandi dimensioni

Test di OTA con Capgo

Il software di Capgo open-source rende facile l'implementazione e il testing degli aggiornamenti in modo rapido. Ecco come utilizzarlo:

1. Configurazione canali di aggiornamento come ad esempio dev, staging e production.
2. L'automazione dei deployment con strumenti CI/CD.
3. L'invio di aggiornamenti istantaneamente.
4. La monitoraggio delle prestazioni e dei problemi tramite il Capgo dashboard.

Per rollout fasi, Capgo consente di limitare gli aggiornamenti a una piccola percentuale di utenti. Ad esempio, puoi distribuire una nuova versione a 25% degli utenti ogni 24 ore:

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

Questa approccio fasi aiuta a identificare gli errori in anticipo sfruttando i feedback della community prima di una rilascio completo.

Processo di Richiesta di Modifica

Una volta che hai testato a fondo le tue modifiche, segui questi passaggi per inviare la tua richiesta di modifica:

Elenco di Controllo per la Sottomissione della PR

Prima di sottoporre, assicurati di aver coperto queste aree chiave:

Linee guida della community

Quando collabori, segui queste migliori pratiche:

• Rispondi velocemente alle feedback dei revisori.
• Tieni le discussioni focalizzate sui dettagli tecnici.
• Utilizza la funzione di proposta di GitHub per proporre code modifiche.
• Inviare richieste di pull piccole e focalizzate che si occupino di una sola funzione o problema alla volta.

Per modifiche più grandi, è una buona idea creare un problema prima e discutere la tua approccio. L'Capacitor team si basa sulle GitHub Actions per i controlli automatizzati, e tutti i controlli devono essere riusciti prima che la tua richiesta di pull possa essere valutata.

Guida di integrazione di Capgo

Se il tuo plugin prevede aggiornamenti in tempo reale, assicurati che funzioni senza problemi con Capgo prima di inviarlo:

1. Versione di controllo
   Usa una versione semantica chiara per il tuo plugin e documenta tutte le modifiche nel changelog. Capgo’s sistema aiuta a monitorare l’adozione della versione su dispositivi utente.

2. Integrazione CI/CD
   Integra Capgo nel tuo pipeline CI/CD per automatizzare le distribuzioni di aggiornamento.

3. Monitoraggio degli aggiornamenti
   Monitora i tassi di successo delle distribuzioni e assicurati di essere conforme alle linee guida degli store di app.

Riepilogo

Per fare una contribuzione significativa con il tuo plugin, è importante seguire il processo stabilito e rispettare gli standard della community. Ciò include l'osservanza delle linee guida di codifica di Capacitor e la verifica approfondita del tuo lavoro.

Il checklist PR sottolinea la necessità di sottoscrizioni di alta qualità. Se il tuo plugin supporta gli aggiornamenti in tempo reale, l'integrazione con Capgo (come menzionato in precedenza) può aiutarti a rilasciare gli aggiornamenti velocemente senza dover attendere l'approvazione degli store di app.

Una volta che il tuo PR è stato integrato, resta coinvolto seguendo le questioni e rilasciando aggiornamenti di versione. L'interazione regolare con la community, la manutenzione costante e l'aggiornamento alle nuove funzionalità di Capacitor assicurerà che il tuo plugin rimanga utile e rilevante.

Prestare attenzione alle informazioni degli utenti e apportare aggiornamenti quando necessario. Questo sforzo continuo aiuta a mantenere la qualità generale dell'ecosistema e mantiene il tuo plugin utile per i developer.

Continua da Capacitor Guida alla Contribuzione del Plugin

Se stai utilizzando Capacitor Guida alla Contribuzione del Plugin per pianificare il lavoro di plugin nativo, connettilo con Capgo Directory dei Plugin per il flusso di lavoro del prodotto in Capgo Directory dei Plugin, Capacitor Plugin di Capgo per i dettagli di implementazione in Capacitor Plugin di Capgo, Aggiungere o Aggiornare i Plugin per i dettagli di implementazione in Aggiungere o Aggiornare i Plugin, Alternative per Plugin Enterprise di Ionic per il workflow del prodotto in Alternative Plugin Enterprise Ionic, e Capgo Costruzioni Native per il workflow del prodotto in Capgo Costruzioni Native.