Capacitor Leitfaden für die Beiträge zum Plugin

Capacitor Plugins verbinden Web-Technologien mit nativen Gerätefunktionen, was eine Cross-Platform-Entwicklung ermöglicht. Diese Anleitung hilft Ihnen:

• Ihre Umgebung einrichten: Werkzeuge wie Node.js, Xcodeund Android Studio wesentliche Werkzeuge.
• Folgen Sie den Code Standards: Verwenden Sie TypeScript, Swiftund Kotlin mit konsistenten Namenskonventionen und Fehlerbehandlungen.
• Testen Sie gründlich: Schreiben Sie Einheitstests für JavaScript, iOS und Android, um Zuverlässigkeit sicherzustellen.
• Dokumentation Schützen: Verwenden Sie JSDoc und README-Dateien für eine einfache Adoption.
• Pull-Request Einreichen: Stellen Sie sicher, dass Sie hochwertige code, Tests und Dokumentation vor der Beitragsabgabe haben.

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 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 Ecosystem 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. Installieren von Abhängigkeiten und Build
   Führen Sie den folgenden Befehl aus, um alles zu installieren, was Sie benötigen, und die Plugins zu bauen:

   npm run build

3. Einrichten der Versionskontrolle
   Verwenden Sie Feature-Zweige für Ihre Änderungen und halten Sie Ihr 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:

• Laden Sie Xcode vom Mac App Store herunter.

• Installieren Sie die Befehlszeilenwerkzeuge mit:

  xcode-select --install

• Installieren Sie CocoaPods mit:

  sudo gem install cocoapods

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

• 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 Sie ein JDK installiert haben.
• Konfigurieren Sie die Android SDK ordnungsgemäß innerhalb von Android Studio.

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

Code Richtlinien-Leitfaden

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

Richtlinien-Leitfaden zur Stilistik

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 zu nutzen. Nutzen Sie außerdem Plattform-spezifische Programmierkonventionen für Swift (iOS) und Kotlin (Android). async/awaitFehler- und Typmanagement

Eine konsistente Fehlerbehandlung ist für die Cross-Plattform-Kompatibilität entscheidend. Hier ist ein Beispiel:

Für die Typsicherheit:

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

Folge dieser Richtlinien, um eine konsistente Fehlerbehandlung zu gewährleisten.

• Benutze fokussierte Schnittstellen, die auf bestimmte Anwendungsfälle zugeschnitten sind.
• Anwende Unionstypen für plattformspezifische Variationen.

Code Dokumentation

Gute Dokumentation ist der Schlüssel, um dein Plugin zugänglich und leicht zu verwenden zu machen. Halte dich an diese Praktiken:

1. API Dokumentation: Schreibe 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: Include essential information like installation steps, configuration instructions, platform-specific requirements, usage examples, and a detailed API reference.

Capacitor

-Referenz hinzu.

Ein gut geschriebenes Dokumentationsmaterial stellt sicher, dass dein Plugin leicht adoptiert werden kann und zum breiteren __CAPGO_KEEP_0__-Community beiträgt.

Die Überprüfung 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 die Kommunikation zwischen JavaScript und native code ordnungsgemäß funktioniert. Um loszulegen, müssen Sie Ihre Testumgebung mit Frameworks einrichten, 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 bestätigt haben, dass die Kernfunktion der Bridge wie erwartet funktioniert, sollten Sie sich auf die Überprüfung vollständiger Benutzerworkflows konzentrieren.

Complete Plugin Tests

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

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

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

OTA-Test mit Capgo

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

Für geschachtelte Rollouts ermöglicht Capgo die Limitierung von Updates auf eine kleine Anzahl 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"
  }
}

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

Pull-Request-Prozess

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

Überprüfungsliste für Pull-Anfragen

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

Community Guidelines

Wenn Sie zusammenarbeiten, sollten Sie diese Best Practices befolgen:

• Reagieren Sie schnell auf Rückmeldungen von Rezensionen.
• Halten Sie Diskussionen auf technische Details fokussiert.
• 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 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 ab, um automatisierte Überprüfungen durchzuführen, und alle Überprüfungen müssen bestanden sein, bevor Ihre Pull-Anfrage überprüft werden kann.

Capgo-Integrationshandbuch

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

1. Versionierung
   Verwenden Sie klare semantische Versionierung für Ihr Plugin und dokumentieren Sie alle Änderungen im Changelog. Capgo’s System hilft dabei, die Versionsadoption über Benutzergeräte zu verfolgen.

2. CI/CD-Integration
   Integriere Capgo in deinen CI/CD-Pipeline, um Updates automatisiert zu deployen.

3. Update-Überwachung
   Überwache die Erfolgsraten der Bereitstellungen und sichere dir die Einhaltung der Richtlinien der App-Stores.

Zusammenfassung

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

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

Sobald dein PR eingereicht wurde, bleibe aktiv, indem du Probleme verfolgst und Updates für deine Version bereitstellst. Regelmäßige Interaktion mit der Community, konsistente Wartung und das Einhalten der Capacitor-Updates sicherstellen, dass dein Plugin nützlich und relevant bleibt.

Beachte die Benutzerfeedback und passe deine Updates entsprechend an. Dieser ständige Aufwand hilft, die Gesamtklasse des Ökosystems aufrechtzuerhalten und dein Plugin für Entwickler wertvoll zu machen.