Capacitor Plugin-Beitritsleitfaden

Capacitor Plugins verbinden Web-Technologien mit nativen Gerätefunktionen, um die Verbindung 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 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

Entwicklungsumgebung Einrichten

Eine ordnungsgemäße 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 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

Das 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. Fork und Clone des Repositorys
   Beginnen Sie mit dem Forken des 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:

• Laden Sie Xcode vom Mac App Store herunter.

• 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) zur Wahrung 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 das 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-Leitfaden

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

Richtlinienkonformität zur Stilrichtlinie

Das Capacitor-Plugin-Ökosystem erzwingt strenge Programmierstandards mit Hilfe 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 async/awaitbenutzen. Fügen Sie außerdem Plattform-spezifische Kodierkonventionen für Swift (iOS) und Kotlin (Android) hinzu.

Error- und Typverwaltung

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 Interfaces, die auf bestimmte Anwendungsfälle zugeschnitten sind.
• Anwenden Sie Unionstypen für plattform-spezifische Variationen.

Code Dokumentation

Gute Dokumentation ist der Schlüssel, um Ihren Plugin zugänglich und leicht zu verwenden zu machen. Führen Sie diese Praktiken aus:

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ühren Sie wichtige Informationen wie Installationsanweisungen, Konfigurationsanweisungen, Plattform-spezifische Anforderungen, Verwendungsexemplare und eine detaillierte API Referenz.

Eine gut geschriebene Dokumentation stellt sicher, dass Ihr Plugin leicht zu adoptieren 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

Die Pröfung der Native Bridge stellt sicher, dass es eine ordnungsgemäße Kommunikation zwischen JavaScript und native code gibt. 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 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 die grundlegende Brückenfunktion bestätigt haben, wechseln Sie zu der Überprüfung vollständiger Benutzerworkflows.

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. Beispielsweise sollten Sie bei einem DeviceInfo-Plugin prüfen, ob:

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

OTA-Test 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. Automatisierung von Bereitstellungen mit CI/CD-Tools.
3. Push-Updates sofort.
4. Überwachen Sie Leistung und Probleme über das Capgo-Dashboard.

Für geschachtelte Rollouts ermöglicht Capgo Ihnen, Updates auf eine kleine Anzahl von Benutzern zu beschränken. 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 geschachtelte 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

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

Überprüfungsliste für die Einreichung

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

Community-Richtlinien

Wenn man zusammenarbeitet, sollten diese besten Praktiken befolgt werden:

• Reagieren Sie schnell auf Rückmeldungen von Rezensionen.
• Halten Sie Diskussionen auf technische Details fokussiert.
• 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 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 Integrationsleitfaden

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 Versionsverlauf. Capgo's System hilft dabei, die Versionsanpassung auf Benutzergeräten zu verfolgen.

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

3. Update-Monitoring
   Überwachen Sie die Erfolgsraten der Bereitstellungen und stellen Sie sicher, dass Sie den Richtlinien der App-Store-Kompatibilität entsprechen.

Zusammenfassung

Um mit Ihrem Plugin einen wertvollen Beitrag zu leisten, ist es wichtig, den etablierten Prozess zu befolgen und die Gemeinschaftsstandards einzuhalten. Dazu gehört, sich an Capacitor's Richtlinien für die Programmierung zu halten und Ihr Werk gründlich zu testen.

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 zu veröffentlichen, ohne auf die Genehmigung der App-Store-Abteilung warten zu müssen.

Nachdem Ihr PR eingereicht wurde, bleiben Sie aktiv, indem Sie sich an den Problemen beteiligen und Version-Updates veröffentlichen. Regelmäßige Interaktion mit der Gemeinschaft, konsistente Wartung und sich mit den Capacitor-Updates auseinander setzen sicherst du so, dass dein Plugin nützlich und relevant bleibt.

Beachte die Nutzerfeedback und passe deine Updates entsprechend an. Diese ständige Anstrengung hilft dabei, die Gesamtklasse des Ökosystems aufrechtzuerhalten und dein Plugin für Entwickler wertvoll zu halten.

Fortsetze mit dem Capacitor-Plugin-Beitragsguide

Wenn du " Capacitor-Plugin-Beitragsguide" zum Planen von nativen Plugin-Arbeiten verwendest, verbinde es mit " Capgo-Plugin-Verzeichnis" for the product workflow in Capgo Plugin Directory, Capacitor Plugins by Capgo Capacitor-Plugins von Capgo" für die Implementierungsdetails in "__CAPGO_KEEP_0__-Plugins von __CAPGO_KEEP_1__", 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.