Capacitor Plugin-Beitritsleitfaden

Capacitor Plugins verbinden Web-Technologien mit nativen Gerätefunktionen, um diese zu ermöglichen Plattformübergreifende App-Entwicklung. 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 Zuverlässigkeit sicherzustellen.
• Dokumentiere Offen: Verwenden Sie JSDoc und README-Dateien für eine einfache Adoption.
• Pull-Anfrage einreichen: Stellen Sie sicher, dass die Qualität der code, Tests und Dokumentation hoch ist, bevor Sie beitragen.

Vollständige Anleitung zur Open-Source-Software - Wie man beiträgt

Entwicklungsumgebung Einrichten

Eine ordnungsgemäße Entwicklungsumgebung ist für eine effiziente Pluginentwicklung von entscheidender Bedeutung. Eine gut vorbereitete Einrichtung 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 Sie die folgenden Werkzeuge installiert haben:

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

Der Capacitor-Plugins Das Ökosystem setzt sich auf eine Monorepo-Struktur ab. Diese Vorgehensweise sichert Ihre Arbeit von Anfang an an den Community-Standards aus.

1. Forken und Repository klonen
   Forken Sie das 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. Abhängigkeiten installieren und bauen
   Führen Sie den folgenden Befehl aus, um alle erforderlichen Abhängigkeiten zu installieren und die Plugins zu bauen:

   npm run build

3. Versionskontrolle einrichten
   Verwenden Sie Featurezweige für Ihre Änderungen und halten Sie Ihre 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:

• Herunterladen Sie Xcode aus dem Mac App Store.

• Installieren Sie die 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 Aufrechterhaltung der code Qualität.

Für Android:

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

Sobald diese Plattformen eingerichtet sind, sind Sie bereit, sich an etablierten Programmierpraktiken zu halten und in die Plugin-Entwicklung einzusteigen.

Code Standards Guide

Da Ihre Entwicklungsumgebung eingerichtet ist, halten Sie sich an diese Richtlinien, um Plugins zu erstellen, die leicht zu warten und zu verwenden sind.

Style Guide Compliance

Die 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 verwenden, um eine bessere Typsicherheit und ES6+-Funktionen wie async/awaitzusätzlich zu den Plattform-spezifischen Programmierkonventionen für Swift (iOS) und Kotlin (Android) einhalten.

Fehler- und Typmanagement

Ein konsistenter Fehlerbehandlung ist für die Cross-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 Interfaces, die auf bestimmte Anwendungsfälle zugeschnitten sind.
• Wenden Sie Unionstypen für plattform-spezifische Variationen an.

Code Dokumentation

Gute Dokumentation ist der Schlüssel zum Zugänglichmachen und leicht zu bedienen Ihres Plugins. Folgen Sie diesen Praktiken:

1. API Dokumentation: Schreiben Sie JSDoc-Kommentare, die mit @capacitor/docgenkompatibel sind. 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 wichtige Informationen wie Installationsanleitungen, Konfigurationsanweisungen, Plattform-spezifische Anforderungen, Verwendungsexemplare und eine detaillierte API-Referenz hinzu.

Eine gut geschriebene Dokumentation stellt sicher, 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 die Fokussierung auf einige kritische Bereiche, um eine glatte Funktionalität und Zuverlässigkeit sicherzustellen.

Native Bridge Tests

Die Prüfung der Native Bridge stellt sicher, dass eine korrekte Kommunikation zwischen JavaScript und native code besteht. Um loszulegen, stellen Sie Ihr Testumfeld 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 die Prüfung 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 die grundlegende Brückenfunktion bestätigt haben, gehen Sie zur Überprüfung vollständiger Benutzerworkflows über.

Vollständige Plugin-Tests

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

Für Plugins mit komplexen Funktionen simulieren Sie realistische Benutzerszenarien. Zum Beispiel, wenn Sie ein Plugin zum Geräteinformationen testen, überprüfen Sie:

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

OTA-Testen mit Capgo

Capgo’s offene Quellcode-Tools 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 Leistung und Probleme über das Capgo-Dashboard.

Für geschaltete Rollouts ermöglicht Capgo die Limitierung von Updates auf einen kleinen Prozentsatz der Benutzer. 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"
  }
}

Diese geschaltete Vorgehensweise hilft, Probleme frühzeitig zu identifizieren, indem sie sich auf Feedback der Community vor einer vollständigen Veröffentlichung stützt.

Pull-Request-Prozess

Nachdem Sie Ihre Änderungen gründlich getestet haben, folgen Sie diesen Schritten, um Ihren Pull-Request abzugeben:

PR-Abgabeliste

Bevor Sie abgeben, stellen Sie sicher, dass Sie diese wichtigen Bereiche abgedeckt haben:

Community-Richtlinien

Wenn man zusammenarbeitet, sollten Sie sich an diese besten Praktiken halten:

• Reagieren Sie schnell auf Rückmeldungen von Rezensionen.
• Bleiben Sie bei technischen Details.
• Verwenden Sie GitHub’s Vorschlagsfunktion, um code Änderungen vorzuschlagen.
• Senden Sie kleine, fokussierte Pull-Anfragen, die sich auf eine Funktion oder ein Problem pro Zeitabschnitt konzentrieren.

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 sich an GitHub-Actions für automatisierte Überprüfungen und alle Überprüfungen müssen erfolgreich sein, bevor Ihre Pull-Anfrage überprüft werden kann.

Capgo Integrationsleutchen

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

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

2. CI/CD-Integration
   Integrieren Sie Capgo in Ihre CI/CD-Pipeline, um die Update-Deployments automatisieren zu können.

3. Update-Monitoring
   Überwachen Sie die Erfolgsraten der Bereitstellungen 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 Community-Standards einzuhalten. Dazu gehört, sich an Capacitor's Coding-Richtlinien zu halten und Ihr Werk gründlich zu testen.

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

Nachdem Ihr PR eingereicht wurde, bleiben Sie involviert, indem Sie sich mit den Problemen auseinandersetzen und Version-Updates veröffentlichen. Regelmäßige Interaktion mit der Community, konsistente Wartung und sich mit den Capacitor-Updates auseinander setzen sicherst du, dass deine Erweiterung nützlich und relevant bleibt.

Achte auf Benutzerfeedback und passe deine Erweiterung entsprechend an. Dieser ständige Aufwand hilft dabei, die Gesamtklasse der Ökosysteme aufrechtzuerhalten und deine Erweiterung für Entwickler wertvoll zu machen.