Capacitor Guida alla Contribuzione del Plugin

Capacitor I plugin __CAPGO_KEEP_0__ collegano tecnologie web con funzionalità di dispositivi nativi, consentendo lo sviluppo di applicazioni cross-platform. sviluppo di applicazioni cross-platformQuesta guida ti aiuta:

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

Guida Completa per Open Source - Come Contribuire

Configurazione 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, un testing e una distribuzione dei plugin fluidi.

Strumenti e Competenze che Avrai Bisogno

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

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

Impostazione della cartella monorepo

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

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

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

2. Installa 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 Nativhe

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 di 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 codifica stabilite e a immergerti nello sviluppo di plugin.

Guida dei Code Standards

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

Guida allo stile di conformità

La Ecosistema dei plugin Capacitor adotta standard di codifica rigorosi utilizzando strumenti come ESLint, Prettier, e SwiftLint. Ecco un breve riassunto delle formattazioni richieste:

I plugin dovrebbero utilizzare TypeScript per una maggiore sicurezza dei tipi e per le funzionalità come ES6+ come async/awaitGestione degli errori e dei tipi

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

Per la sicurezza dei tipi:

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

Plugins should use TypeScript for better type safety and ES6+ features like

• Utilizza interfacce focalizzate adattate a casi d'uso specifici.
• Applica tipi di unione per 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/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 passaggi di installazione, istruzioni di configurazione, requisiti specifici delle piattaforme, 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 prevede di concentrarsi su alcune aree critiche per garantire una funzionalità e affidabilità ottimali.

Test del Bridge Nativo

I test del bridge nativo assicurano una comunicazione corretta tra JavaScript e code. Per iniziare, configurare l'ambiente di testing con framework specifici per ogni piattaforma.

Ecco un esempio di un 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, utilizzare 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 bridge core funziona come previsto, procedere con la verifica di flussi di lavoro completi.

Test dei Plugin Completi

Per assicurarsi che il plugin funzioni bene in diversi scenari, testare 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_KEEP_0__ Test di OTA con Capgo

Capgo strumenti open-source rendono facile la distribuzione e il testing degli aggiornamenti in modo rapido. Ecco come utilizzarli:

1. Configurazione canali di aggiornamento come ad esempio dev, staging e produzione
2. Automatizzare le distribuzioni con strumenti CI/CD
3. Invia gli aggiornamenti istantaneamente
4. Monitorare le prestazioni e i problemi tramite il Capgo dashboard.

Per i rilasci fasi, Capgo consente di limitare gli aggiornamenti a un piccolo numero 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 i problemi in anticipo sfruttando i feedback della community prima di un 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 pull:

Checklist di invio della PR

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

Community Guidelines

Quando collabori, segui queste linee guida:

• Rispondi velocemente 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 funzione o problema alla volta.

Per modifiche più grandi, è una buona idea creare un issue prima e discutere la tua approccio. Il team di Capacitor si basa sulle GitHub Actions per controlli automatizzati, e tutti i controlli devono superare 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. Controllo delle versioni
   Utilizza una versione semantica chiara per il tuo plugin e documenta tutte le modifiche nel changelog. Il sistema di Capgo aiuta a tracciare l'adozione delle versioni su dispositivi degli utenti.

2. Integrazione CI/CD
   Integra Capgo nella tua pipeline CI/CD per automatizzare gli aggiornamenti di distribuzione.

3. Aggiornamento di Monitoraggio
   Monitorare i tassi di successo di distribuzione e assicurarsi che le linee guida degli store di app siano rispettate.

Riepilogo

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

Il checklist PR evidenzia 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 aggiornamenti velocemente senza dover attendere l'approvazione degli store di app.

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

Dai attenzione alle feedback 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 developer.