Guida alla Contribuzione del Plugin Capacitor

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

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

Guida Completa per Open Source - Come Contribuire

Configurazione dell'ambiente di sviluppo

Creare un ambiente di sviluppo adeguato è fondamentale per un efficiente sviluppo di plugin. Una configurazione ben preparata consente una codifica, test e deployment fluidi dei tuoi plugin.

Strumenti e competenze che avrai bisogno

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

Devi essere anche 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 monorepo

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

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

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

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

   npm run build

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

Preparare le 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.

• Install command-line tools using:

  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 il SDK Android all'interno di Android Studio.

Una volta configurati questi piattaforme, sarai pronto a seguire le pratiche di codifica stabilite e a 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.

Linea Guida di Stile

La Capacitor ecosistema di plugin adotta rigorosi standard di codifica 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+. async/awaitSeguono inoltre le convenzioni di codifica specifiche per piattaforma 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 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 READMEIncludere informazioni essenziali come passaggi di installazione, istruzioni di configurazione, requisiti specifici per piattaforma, 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 alla verifica dei plugin

Testare i plugin Capacitor comporta un focus su alcune aree critiche per garantire una funzionalità e affidabilità fluida.

Test delle bridge native

I test delle bridge native 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 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à di ponte di base, procedere con il testing di flussi di lavoro completi.

Test di Plugin Completi

Per garantire che il tuo plugin si comporti bene in diversi scenari, testare varie categorie:

Per i plugin con funzionalità complesse, simulare scenari di utilizzo realistici. Ad esempio, se stai testando un plugin DeviceInfo, controlla per:

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

Test di OTA con Capgo

Capgo's strumenti open-source rendono facile l'implementazione e il test di aggiornamenti rapidi. Ecco come utilizzarli:

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

Per 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 gli errori 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 pull.

Elenco di Controllo per la Sottomissione

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

Linee guida della community

Quando collabori, segui queste migliori pratiche:

• Rispondi rapidamente alle feedback dei revisori.
• Tieni le discussioni focalizzate sui dettagli tecnici.
• Usa la funzione di suggerimento di GitHub per proporre code modifiche.
• Invia richieste di pull con pochi cambiamenti, focalizzate su una sola funzione o problema alla volta.

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

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
   Usa una versione semantica chiara per il tuo plugin, e documenta tutte le modifiche nel changelog. Il sistema di Capgo aiuta a monitorare l'adozione della versione su dispositivi utente.

2. Integrazione CI/CD
   Integra Capgo nella tua pipeline CI/CD per automatizzare le distribuzioni di aggiornamento.

3. Monitoraggio degli aggiornamenti
   Monitora i tassi di successo delle distribuzioni e assicurati di rispettare le 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 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 aggiornamenti velocemente senza dover attendere l'approvazione delle app store.

Rimani coinvolto rimanendo aggiornato sulle questioni e rilasciando aggiornamenti di versione. Interagisci regolarmente con la community, assicurati la manutenzione costante e l'aggiornamento alle Capacitor aggiornamenti assicureranno che il tuo plugin rimanga utile e pertinente.

Prendi in considerazione le recensioni degli utenti e aggiorna il tuo plugin in base alle esigenze. Questo sforzo continuo aiuta a mantenere la qualità generale dell'ecosistema e mantiene il tuo plugin utile per i developer.

Continua con il Guida di Contribuzione del Plugin Capacitor

Se stai utilizzando Guida di Contribuzione del Plugin Capacitor per pianificare il lavoro di plugin nativo, connettilo con Capgo Plugin Directory per il workflow del prodotto nella Capgo Directory dei Plugin Capacitor Plugin da Capgo per il dettaglio di implementazione in Capacitor Plugin da Capgo Aggiunta o Aggiornamento di Plugin per il dettaglio di implementazione in Aggiunta o Aggiornamento di Plugin Sostituti di Plugin Enterprise Ionic per il workflow del prodotto in Sostituti di Plugin Enterprise Ionic, e Capgo Costruzione Nativa per il workflow del prodotto in Capgo Costruzione Nativa.