Guida di Contribuzione al Plugin Capacitor

Capacitor I plugin __CAPGO_KEEP_0__ connettono tecnologie web con funzionalità di dispositivo nativo, consentendo l'accesso sviluppo di applicazioni cross-platform. Questa guida ti aiuta:

• Configura il tuo ambiente: Strumenti come Node.js, Xcode, e Android Studio sono essenziali.
• Segui i Code Standards: Utilizza TypeScript, Swift, e Kotlin con gli convenzioni di denominazione coerenti e il gestione degli errori.
• Testa Thoroughmente: 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 avere un code, testing di alta qualità e documentazione prima di contribuire.

Guida Completa all'Open Source - Come Contribuire

Impostazione dell'ambiente di sviluppo

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

Strumenti e competenze che avrai bisogno

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

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].

Configurazione della repository monolitica

Il Capacitor plugin l'ecosistema si basa su una struttura di repository monolitica. Questo approccio assicura che il tuo lavoro si allinei con gli standard della community fin dall'inizio

1. Fork e Clona il Repository
   Inizia forkando il repository dei Capacitor plugin su GitHub. Poi, clona la tua fork del repository:

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

2. Installare Dipendenze e Costruire
   Eseguire il seguente comando per installare tutto ciò di cui hai bisogno e costruire i plugin:

   npm run build

3. Configurare il Controllo delle Versioni
   Usare rami di feature per le tue modifiche e mantenere 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:

• Scaricare Xcode dal Mac App Store.

• Installare gli strumenti di linea di comando utilizzando:

  xcode-select --install

• Installare CocoaPods con:

  sudo gem install cocoapods

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

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

Per Android:

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

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

Code Standards Guide

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

Style Guide Compliance

Il Capacitor plugin ecosystem applica standard di codifica rigorosi utilizzando strumenti come ESLint, Prettier, e SwiftLint. Ecco una panoramica rapida delle formattazioni richieste:

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

Gestione degli Errori e dei Tipi

Una gestione degli errori coerente è cruciale 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 le variazioni specifiche delle piattaforme.

Code Documentazione

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

1. API Documentazione: Scrivi commenti JSDoc che funzionano con @capacitor/docgenPer 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: Includere informazioni essenziali come le istruzioni di installazione, le istruzioni di configurazione, le specifiche delle piattaforme, gli esempi di utilizzo e una dettagliata API documentazione.

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

sbb-itb-f9944d2

Guida per la verifica dei plugin

La verifica dei plugin Capacitor consiste nell'attenersi a poche aree critiche per garantire una funzionalità liscia e affidabile.

Test del ponte nativo

I test del ponte nativo assicurano 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 la verifica 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à della passerella di base, procedi con la verifica delle workflow complete degli utenti.

Test dei Plugin completi

Per assicurarti 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 stai testando un plugin DeviceInfo, controlla per: __CAPGO_KEEP_0__

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

Test di aggiornamento OTA con Capgo

Capgo dispone di strumenti open-source facili da utilizzare per la distribuzione e il test delle aggiornamenti in modo rapido. Ecco come utilizzarli:

1. Configurazione canali di aggiornamento come dev, staging e production.
2. L'automazione dei deployment con strumenti CI/CD.
3. Invia aggiornamenti istantaneamente.
4. Monitorare le prestazioni e i problemi tramite il Capgo dashboard.

Per i rilasci fasi, Capgo consente di limitare gli aggiornamenti a una piccola percentuale di utenti. Ad esempio, puoi rilasciare 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 i problemi in anticipo sfruttando i feedback della community prima di un rilascio completo.

Processo di Richiesta di Modifica

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

Elenco di Controllo per la Sottoscrizione

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

Linee guida della community

Quando collabori, adotta queste migliori pratiche:

• Rispondi rapidamente alle feedback dei revisori.
• Mantieni le discussioni focalizzate sui dettagli tecnici.
• Utilizza la funzione di proposta di GitHub per proporre code modifiche.
• Invia richieste di pull piccole e focalizzate che si occupano di una sola funzionalità o problema alla volta.

Per modifiche più grandi, è una buona idea creare un problema prima e discutere la tua approccio. Il team di Capacitor si appoggia sulle GitHub Actions per le verifiche automatizzate, e tutte le verifiche devono essere riuscite prima che la tua richiesta di pull possa essere revisionata.

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. Controllo delle versioni
   Utilizza una versioning semantica chiara per il tuo plugin e documenta tutte le modifiche nel changelog. Il sistema di Capgo aiuta a monitorare l'adozione delle versioni su dispositivi degli utenti.

2. Integrazione CI/CD
   Integra Capgo nel tuo pipeline CI/CD per automatizzare i deployment degli aggiornamenti.

3. Monitoraggio degli aggiornamenti
   Monitora i tassi di successo dei deployment 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.

La checklist del PR sottolinea la necessità di invii 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.

Dopo che il tuo PR è stato merge, rimani coinvolto seguendo le issue e rilasciando aggiornamenti delle versioni. L'interazione regolare con la community, la manutenzione costante e mantenere l'aggiornamento con Capacitor aggiornamenti assicurerà che il tuo plugin rimanga utile e pertinente.

Fai attenzione alle recensioni degli utenti e aggiorna il tuo plugin quando necessario. Questo sforzo continuo aiuta a mantenere la qualità generale dell'ecosistema e mantiene il tuo plugin utile per i sviluppatori.