Capacitor Plugin Contribution Guide

Capacitor Plugins verbinden Web-Technologien mit nativen Gerätefunktionen, um die Entwicklung von Apps für mehrere Plattformen zu ermöglichen. Diese Anleitung hilft Ihnen:

• Ihre Umgebung einrichten: Werkzeuge wie Node.js, Xcode, und Android Studio sind unerlässlich.
• Folgen Sie den Code Standards: Verwenden Sie TypeScript, Swift, und Kotlin mit konsistenten Namenskonventionen und Fehlerbehandlung.
• Gründlich testen: Schreiben Sie Einheitstests für JavaScript, iOS und Android, um die Zuverlässigkeit sicherzustellen.
• Dokumentiere klar: Verwenden Sie JSDoc und README-Dateien für eine einfache Adoption.
• Pull-Request einreichen: Stellen Sie sicher, dass die Qualität hoch ist, code, die Tests und die Dokumentation, bevor Sie beitragen.

Vollständiger Leitfaden für Open-Source - Wie man beiträgt

Einrichtung der Entwicklungsumgebung

Eine ordnungsgemäße Einrichtung der Entwicklungsumgebung ist für eine effiziente Pluginentwicklung von entscheidender Bedeutung. Eine gut vorbereitete Konfiguration ermöglicht eine glatte Kodierung, Testung und Bereitstellung Ihrer Plugins.

Werkzeuge und Fähigkeiten, die Sie benötigen

Bevor Sie beginnen, stellen Sie sicher, dass die folgenden Werkzeuge installiert sind:

Sie sollten sich auch mit TypeScript für Webentwicklung und entweder Swift (für iOS) oder Java/Kotlin (für Android) für native Entwicklungsaufgaben auskennen [1][2].

Einrichten des Monorepos

Die Capacitor-Plugins Das Ecosystem setzt sich auf eine Monorepo-Struktur ab. Diese Vorgehensweise sichert Ihre Arbeit von Anfang an mit den Community-Standards ab.

1. Das Repository fürken und klonen
   Beginnen Sie mit dem Forken der Capacitor-Plugins-Repository auf GitHub. Dann klonen Sie Ihr geforktes Repository:

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

2. Ablauf der Abhängigkeiten und Build
   Führen Sie den folgenden Befehl aus, um alles, was Sie benötigen, zu installieren und die Plugins zu bauen:

   npm run build

3. Set Up Version Control
   Verwenden Sie Featurezweige für Ihre Änderungen und halten Sie Ihren Fork mit dem upstream-Repository synchron.

Vorbereitung von Native Plattformen

Für die Cross-Plattform-Entwicklung müssen Sie sowohl die iOS- als auch die Android-Umgebungen konfigurieren.

Für iOS:

• Laden Sie Xcode vom Mac App Store herunter.

• Installieren Sie Befehlszeilenwerkzeuge mit:

  xcode-select --install

• Installieren Sie CocoaPods mit:

  sudo gem install cocoapods

• Richten Sie ein Apple-Entwicklerkonto und die notwendigen Zertifikate ein.

• Verwenden Sie SwiftLint (optional) für die code Qualitätserhaltung.

Für Android:

• Installieren Sie Android Studio zusammen mit dem neuesten SDK und einem virtuellen Gerät.
• Stellen Sie sicher, dass ein JDK installiert ist.
• Konfigurieren Sie den Android-Bereich SDK ordnungsgemäß innerhalb von Android Studio.

Sobald diese Plattformen eingerichtet sind, seid ihr bereit, etablierte Programmierpraktiken zu befolgen und in die Plugin-Entwicklung einzusteigen.

Code-Standards-Leitfaden

Nun, dass Ihr Entwicklungsumfeld eingerichtet ist, halten Sie sich an diese Richtlinien, um Plugins zu erstellen, die leicht zu warten und zu verwenden sind.

Style-Leitfaden-Konformität

Der Capacitor-Plugin-Ökosystem erzwingt strenge Programmierstandards mithilfe von Werkzeugen wie ESLint, Prettier, und SwiftLint. Hier ist eine kurze Übersicht über die erforderliche Formatierung:

Plugins sollten TypeScript für bessere Typsicherheit und ES6+-Funktionen wie verwenden. Zusätzlich sollten sie Plattform-spezifische Programmierkonventionen für Swift (iOS) und Kotlin (Android) einhalten. async/await__CAPGO_KEEP_0__

Fehler- und Typ-Management

Ein konsistenter Fehlerbehandlung ist für die Plattform-Kompatibilität entscheidend. Hier ist ein Beispiel:

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

Für die Typsicherheit:

• Verwenden Sie fokussierte Schnittstellen, die auf bestimmte Anwendungsfälle zugeschnitten sind.
• Anwenden Sie Union-Typen für plattform-spezifische Variationen.

Code Dokumentation

Gute Dokumentation ist der Schlüssel, um Ihren Plugin zugänglich und leicht zu verwenden zu machen. Folgen Sie diesen Praktiken:

1. API Dokumentation: Schreiben Sie JSDoc-Kommentare, die mit @capacitor/docgen. Zum Beispiel:

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

2. README-Struktur: Fügen Sie wesentliche Informationen wie Installationsanweisungen, Konfigurationsanweisungen, plattform-spezifische Anforderungen, Verwendungsexempel und eine detaillierte API-Referenz hinzu.

Gute Dokumentation sichert vor, dass Ihr Plugin leicht zu übernehmen ist und zum breiteren Capacitor-Community beiträgt.

sbb-itb-f9944d2

Plugin-Testleitfaden

Das Testen von Capacitor-Plugins beinhaltet das Fokussieren auf einige kritische Bereiche, um eine glatte Funktion und Zuverlässigkeit sicherzustellen.

Native Bridge Tests

Das Testen der Native Bridge sichert eine ordnungsgemäße Kommunikation zwischen JavaScript und native code. Um loszulegen, stellen Sie bitte Ihre Testumgebung mit Frameworks ein, die auf jede Plattform zugeschnitten sind.

Hier ist ein Beispiel für ein Jest Einheitstest für die JavaScript-Seite:

// 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);
  });
});

Für das Testen auf der native Seite verwenden Sie XCTest für iOS und JUnit für Android. Hier ist ein Beispiel für Android:

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

Sobald Sie bestätigt haben, dass die Kernfunktion der Bridge wie erwartet funktioniert, wechseln Sie zu dem Testen von vollständigen Benutzerworkflows.

Complete Plugin Tests

Sicherstellen, dass Ihr Plugin in verschiedenen Szenarien gut funktioniert, testen Sie verschiedene Kategorien:

Für Plugins mit komplexen Funktionen simulieren Sie realistische Benutzerszenarien. Für beispielsweise ein DeviceInfo-Plugin überprüfen Sie:

• Erfolgreiche Uploads unter verschiedenen Netzwerkbedingungen
• Genauere Fortschrittsberichte
• Speicherplatzverbrauch während großer Dateiübertragungen

OTA-Test mit Capgo

Capgo’s offene Werkzeuge machen es einfach, Updates schnell zu deployen und zu testen. Hier ist, wie man es verwendet:

1. Einrichten Update-Kanäle wie z.B. dev, staging und production
2. Automatisieren Sie die Bereitstellung mit CI/CD-Tools.
3. Pushen Sie Updates sofort.
4. Überwachen Sie die Leistung und Probleme über das Capgo-Dashboard.

Für geschachtelte Rollouts ermöglicht Capgo die Limitierung von Updates auf einen kleinen Prozentsatz von Benutzern. Zum Beispiel können Sie eine neue Version alle 24 Stunden an 25% der Benutzer ausrollen:

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

Dieser geschachtelte Ansatz hilft, Probleme frühzeitig zu identifizieren, indem er sich auf Community-Feedback vor einer vollständigen Veröffentlichung stützt.

Pull-Anforderungs-Prozess

Sobald Sie Ihre Änderungen gründlich getestet haben, folgen Sie diesen Schritten, um Ihre Pull-Anforderung einzureichen:

Überprüfungsliste für die Einreichung

Bevor Sie einreichen, stellen Sie sicher, dass Sie diese Schlüsselfelder abgedeckt haben:

Community-Richtlinien

Wenn Sie zusammenarbeiten, achten Sie auf diese besten Praktiken:

• Reagieren Sie schnell auf Rückmeldungen des Rezensenten.
• Behalten Sie die Diskussionen auf technische Details beschränkt.
• Verwenden Sie GitHub’s Vorschlagsfunktion, um code Änderungen vorzuschlagen.
• Stellen Sie kleine, fokussierte Pull-Anfragen ein, die sich auf eine Funktion oder ein Problem pro Zeitabschnitt beschränken.

Für größere Änderungen ist es eine gute Idee, vorher ein Issue zu erstellen und Ihre Vorgehensweise zu diskutieren. Das Capacitor-Team hängt von GitHub Actions für automatisierte Überprüfungen ab, und alle Überprüfungen müssen erfolgreich sein, bevor Ihre Pull-Anfrage überprüft werden kann.

Capgo-Integrationshandbuch

Wenn Ihr Plugin live-aktuelle Updates beinhaltet, stellen Sie sicher, dass es reibungslos mit Capgo funktioniert, bevor Sie es einreichen:

1. Versionierung
   Verwenden Sie eine klare semantische Versionsnummerierung für Ihr Plugin und dokumentieren Sie alle Änderungen im Versionsverlauf. Capgo’s System hilft dabei, die Versionsanpassung auf Benutzergeräten zu verfolgen.

2. Integration in CI/CD
   Integrieren Sie Capgo in Ihren CI/CD-Pipeline, um die automatisierte Bereitstellung von Updates zu ermöglichen.

3. Überwachung von Updates
   Überwachen Sie die Erfolgsraten der Bereitstellung und stellen Sie sicher, dass Sie den Richtlinien der App-Stores entsprechen.

Zusammenfassung

Um mit Ihrem Plugin einen wertvollen Beitrag zu leisten, ist es wichtig, den etablierten Prozess zu befolgen und die Gemeinschaftsstandards einzuhalten. Dies umfasst das Einhalten der Capacitor-Richtlinien für die Programmierung und eine gründliche Testung Ihres Werks.

Der PR-Checkliste unterstreicht die Notwendigkeit hochwertiger Einreichungen. Wenn Ihr Plugin Live-Updates unterstützt, kann die Integration mit Capgo (wie bereits erwähnt) Ihnen dabei helfen, Updates schnell ohne Wartezeit auf die Genehmigung der App-Stores zu veröffentlichen.

Nachdem Ihr PR eingereicht wurde, bleiben Sie aktiv, indem Sie sich um die Bearbeitung von Issues kümmern und Versionen aktualisieren. Regelmäßige Interaktion mit der Gemeinschaft, konsistente Wartung und die Aktualisierung von Capacitor sorgen dafür, dass Ihr Plugin nützlich und relevant bleibt.

Beachten Sie die Benutzerfeedback und aktualisieren Sie, wenn nötig. Diese laufende Anstrengung hilft dabei, die Gesamtklasse der Ökosystem zu wahren und macht Ihr Plugin für Entwickler wertvoll.

Fortsetzen Sie mit dem Plugin Contribution Guide Capacitor

Wenn Sie Capacitor Plugin Contribution Guide für die Planung von native Plugin-Arbeiten verwenden, verbinden Sie es mit Capgo Plugin Directory für den Produktworkflow in Capgo Plugin Directory, Capacitor Plugins von Capgo für die Implementierungsdetails in Capacitor Plugins von Capgo, Hinzufügen oder Aktualisieren von Plugins für die Implementierungsdetails in Hinzufügen oder Aktualisieren von Plugins, Ionic Enterprise Plugin Alternativen für das Produktworkflow in Ionic Enterprise Plugin Alternativen, und Capgo Native Builds für das Produktworkflow in Capgo Native Builds.