Capacitor Plugin Contribution Guide

Capacitor Plugins verbinden Web-Technologien mit nativen Gerätefunktionen, um Cross-Plattform-App-Entwicklung Dieses 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.
• 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-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 beitragen kann

Entwicklungsumgebung Einrichtung

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].

Einrichtung des Monorepos

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

1. Forken und das Repository klonen
   Beginnen Sie damit, das Capacitor-Plugins-Repository auf GitHub zu forken. Klonen Sie dann 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 der Native-Plattformen

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

Für iOS:

• Xcode von der Mac App Store herunterladen.

• Installieren Sie die Befehlszeilenwerkzeuge mit:

  xcode-select --install

• Installieren Sie CocoaPods mit:

  sudo gem install cocoapods

• Einrichten Sie ein Apple-Entwicklerkonto und die erforderlichen Zertifikate.

• Verwenden Sie SwiftLint (optional) zur 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 ein JDK installiert ist.
• Konfigurieren Sie das Android SDK ordnungsgemäß innerhalb von Android Studio.

Sobald diese Plattformen eingerichtet sind, sind Sie bereit, etablierte Programmierpraktiken zu befolgen und in die Pluginentwicklung einzusteigen.

Code Standards Guide

Nachdem Ihr Entwicklungsumfeld eingerichtet ist, halten Sie sich an diese Richtlinien, um Plugins zu erstellen, die leicht zu pflegen 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 für bessere Typsicherheit und ES6+-Funktionen wie async/await. Benutzen Sie außerdem plattform-spezifische Kodierkonventionen für Swift (iOS) und Kotlin (Android).

Fehler- und Typmanagement

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.
• Anwenden Sie Unionstypen für plattform-spezifische Variationen.

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 wesentliche Informationen wie Installationsanweisungen, Konfigurationsanweisungen, Plattform-spezifische Anforderungen, Verwendungsexempel und eine detaillierte API-Referenz hinzu.

Gute 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 die Fokussierung auf einige kritische Bereiche, um eine glatte Funktionalität und Zuverlässigkeit sicherzustellen.

Native Bridge Tests

Die Überprüfung der Native Bridge stellt sicher, dass eine korrekte 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 Überprü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ückefunktion 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. Zum Beispiel, wenn Sie ein Plugin zum Geräteinformationen testen, überprüfen Sie:

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

OTA-Testen mit Capgo

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

1. Einstellungen 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ühren Sie für die Phasenrollouts Capgo durch, um 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"
  }
}

Dieser phasenweise Ansatz hilft, Probleme frühzeitig zu identifizieren, indem er sich auf die Rückmeldung 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-Submission-Checkliste

Bevor Sie abgeben, 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.
• 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 Mal konzentrieren.

Für größere Änderungen ist es eine gute Idee, vorher eine 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 vor der Einreichung reibungslos mit Capgo funktioniert:

1. Versionierung
   Use clear semantic versioning for your plugin, and document all changes in the changelog. Capgo’s system helps track version adoption across user devices.

2. Verwenden Sie eine klare semantische Versionsierung für Ihr Plugin und dokumentieren Sie alle Änderungen im Versionsverlauf. __CAPGO_KEEP_0__'s System hilft dabei, die Versionsanpassung auf Benutzergeräten zu verfolgen.
   Integrate Capgo into your CI/CD pipeline to automate update deployments.

3. Kontext: Seite/Bereich: Capgo-Bauer / native Cloud-Build-Produktseite. Rolle: Kurzer UI-Label oder Navigationselement. Nachrichtenschlüssel `native_build_feature_ci_cd` (Native Build Feature Ci Cd).
   Integrieren Sie __CAPGO_KEEP_0__ in Ihre CI/CD-Pipeline, um die automatisierte Bereitstellung von Updates zu ermöglichen.

Update-Monitoring

To make a meaningful contribution with your plugin, it’s important to follow the established process and meet community standards. This includes sticking to Capacitor’s coding guidelines and thoroughly testing your work.

The PR checklist highlights the need for high-quality submissions. If your plugin supports live updates, integrating with Capgo (as mentioned earlier) can help you release updates quickly without waiting for app store approvals.

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 die __CAPGO_KEEP_0__-Entwicklerrichtlinien zu halten und Ihr Werk gründlich zu testen. mit den Capacitor Aktualisierungen Schritt halten wird sicherstellen, dass Ihr Plugin nützlich und relevant bleibt.

Beachten Sie die Benutzerfeedback und aktualisieren Sie Ihr Plugin, wenn nötig. Diese ständige Anstrengung hilft dabei, die Gesamtklasse der Ökosystem zu erhalten und Ihr Plugin für Entwickler wertvoll zu halten.

Fortsetzen Sie mit der Capacitor Plugin-Beitragsguide

Wenn Sie __CAPGO_KEEP_0__ Plugin-Beitragsguide verwenden um native Plugin-Arbeit zu planen, verbinden Sie es mit Capacitor Plugin-Verzeichnis um den Produktworkflow in __CAPGO_KEEP_0__ Plugin-Verzeichnis zu erhalten. Capgo Plugins von __CAPGO_KEEP_1__ um die Implementierungsdetails in Capgo Plugins von __CAPGO_KEEP_1__ zu erhalten. Capacitor Plugins von Capgo um die Implementierungsdetails in Capacitor Plugins von Capgo zu erhalten. Hinzufügen oder Aktualisieren von Plugins Für die Implementierungsdetails in Adding or Updating Plugins, Ionische Enterprise-Plugin-Alternativen Für die Produktworkflow in Ionische Enterprise-Plugin-Alternativen, und Capgo Native Builds Für die Produktworkflow in Capgo Native Builds.