Capacitor-Plugin-Beitragsguide

Capacitor Web-Technologien mit nativen Gerätefunktionen verbinden, um eine Plattformübergreifende App-EntwicklungDieses Leitfaden 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.
• Testen Sie gründlich: Schreiben Sie Einheitstests für JavaScript, iOS und Android, um Zuverlässigkeit sicherzustellen.
• Dokumentieren Sie klar: Verwenden Sie JSDoc und README-Dateien für eine einfache Adoption.
• Eine Pull-Anfrage 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

Einstellung der Entwicklungsumgebung

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

Einrichtung des Monorepos

Das Capacitor-Plugins Die Ökosystem basiert auf einer Monorepo-Struktur. Diese Vorgehensweise sichert Ihre Arbeit von Anfang an mit den Gemeinschaftsstandards ab.

1. Forken und klonen Sie das Repository
   Beginnen Sie damit, das Capacitor-Plugin-Repository auf GitHub zu forkten. Klonen Sie dann Ihr geforktes Repository:

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

2. Installieren Sie Abhängigkeiten und erstellen Sie
   Laufen Sie die folgende Kommandozeilenanweisung aus, um alles zu installieren, was Sie benötigen, und die Plugins zu erstellen:

   npm run build

3. Einstellungen für die Versionskontrolle
   Verwenden Sie Featurezweige für Ihre Änderungen und halten Sie Ihr Fork mit dem upstream-Repository synchron.

Vorbereitung der nativen Plattformen

Für die Cross-Plattform-Entwicklung benötigen Sie die Konfiguration sowohl für iOS als auch für Android.

Für iOS:

• Laden Sie Xcode vom Mac App Store herunter.

• Installieren Sie die Kommandozeilenwerkzeuge mit:

  xcode-select --install

• Installieren Sie CocoaPods mit:

  sudo gem install cocoapods

• Ein Apple-Entwicklerkonto und die notwendigen Zertifikate einrichten.

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

Für Android:

• Installieren Sie Android Studio zusammen mit der neuesten SDK und einem virtuellen Gerät.
• Stellen Sie sicher, dass Sie ein JDK installiert haben.
• Konfigurieren Sie die Android SDK ordnungsgewohnt innerhalb von Android Studio.

Einmal diese Plattformen eingerichtet, sind Sie bereit, sich an etablierten Programmierpraktiken zu halten und in die Pluginentwicklung einzutauchen.

Code-Standards-Leitfaden

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

Style-Leitfaden-Konformität

Die Capacitor-Plugin-Ökosystem erzwinge strenge Programmierstandards mit Hilfe von Werkzeugen wie ESLint, Prettierund SwiftLint. Hier ist eine kurze Übersicht der erforderlichen Formatierungen:

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) zu verwenden.

Fehler- und Typenmanagement

Konsistente 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

__CAPGO_KEEP_0__ Dokumentation

1. API Documentation: 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, Verwendungsexemple 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 ordnungsgemäße Kommunikation zwischen JavaScript und native code besteht. Um loszulegen, stellen Sie ein Testumfeld mit Frameworks auf, 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 Testung auf der nativen 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)
}

Wenn Sie bestätigt haben, dass die Kernbrückefunktion wie erwartet funktioniert, gehen Sie zur Testung vollständiger Benutzerworkflows über.

Vollständige Plugin-Tests

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

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

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

OTA-Testen mit Capgo

Capgo’s offene Quellcode-Tools erleichtern die schnelle Bereitstellung und Testung von Updates. Hier erfahren Sie, wie Sie es verwenden können:

1. Konfiguration 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 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"
  }
}

Dieser geschaltete Ansatz hilft, Probleme frühzeitig zu erkennen, indem er sich auf die Rückmeldung der Community vor einer vollständigen Veröffentlichung stützt.

Pull-Request-Prozess

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

Überprüfungsliste für den Pull-Request

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

Community-Richtlinien

Wenn Sie zusammenarbeiten, achten Sie auf diese Best Practices:

• Reagieren Sie schnell auf Rückmeldungen von Rezensionen.
• 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 Mal 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 vor der Überprüfung Ihres Pull-Anfragen erfolgreich sein.

Capgo-Integration-Leitfaden

Wenn Ihr Plugin live-Updates beinhaltet, stellen Sie sicher, dass es vor der Einreichung problemlos mit Capgo funktioniert:

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

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

3. Update-Monitoring
   Ü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. Dazu gehört, sich an Capacitor's Coding-Richtlinien zu halten und Ihr Werk gründlich zu testen.

Die PR-Übersicht hebt die Notwendigkeit von hochwertigen Einreichungen hervor. Wenn Ihr Plugin Live-Updates unterstützt, kann die Integration mit Capgo (wie bereits erwähnt) Ihnen helfen, Updates schnell ohne Wartezeit auf Genehmigung durch den App-Store zu veröffentlichen.

Nachdem Ihr Pull-Request eingereicht wurde, bleibt es wichtig, sich an den Diskussionen zu beteiligen und Updates für Ihre Version bereitzustellen. Regelmäßige Interaktion mit der Community, konsistente Wartung und das die Einhaltung von Capacitor-Updates werden sicherstellen, dass Ihr Plugin nützlich und relevant bleibt.

Beachten Sie die Benutzerfeedback und machen Sie Updates, wenn nötig. Dieser ständige Aufwand hilft dabei, die Gesamtklasse des Ökosystems aufrechtzuerhalten und Ihr Plugin wertvoll für Entwickler zu halten.

Fortsetzen Sie mit der Anleitung zum Beitrag von Capacitor-Plugins

Wenn Sie __CAPGO_KEEP_0__-Plugin-Beitrag-Anleitung verwenden um native Plugin-Arbeit zu planen, verbinden Sie es mit Capacitor-Plugin-Verzeichnis um den Produktfluss in __CAPGO_KEEP_0__-Plugin-Verzeichnis Capgo-Plugins von __CAPGO_KEEP_1__ Capgo ist ein Hinweis auf Capacitor Capacitor Plugins by Capgo Für die Implementierungsdetails in Capacitor Plugins durch Capgo Plugins hinzufügen oder aktualisieren Für die Implementierungsdetails in Plugins hinzufügen oder aktualisieren Ionische Unternehmens-Plugin-Alternativen Für das Produktworkflow in Ionische Unternehmens-Plugin-Alternativen und Capgo Native Builds Für das Produktworkflow in Capgo Native Builds.