Capacitor-Plugin-Beitragsguide

Capacitor Plugins verbinden Web-Technologien mit nativen Gerätefunktionen, um Plattformübergreifende App-Entwicklung. Diese Anleitung hilft Ihnen:

• Umgebung einrichten: Werkzeuge wie Node.js, Xcode, und Android Studio sind unerlässlich.
• Folgen Sie den Code Standards: Use 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.
• Stellen Sie einen Pull-Request ein: Stellen Sie sicher, dass Sie hochwertige code, Tests und Dokumentation vor der Beitragsabgabe haben.

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 Das Ecosystem setzt sich auf eine monorepo-Struktur ab. Diese Vorgehensweise sichert, dass Ihre Arbeit von Anfang an mit den Community-Standards übereinstimmt.

1. Forken und Repository klonen
   Beginnen Sie damit, das Capacitor-Plugin-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
   Laufen Sie den folgenden Befehl aus, um alles zu installieren, was Sie benötigen, und die Plugins zu bauen:

   npm run build

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

Vorbereitung der Native-Plattformen

Für die Cross-Platform-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 Befehlszeilen-Tools mit:

  xcode-select --install

• Install 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 der 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, sich an etablierten Programmierpraktiken zu halten und in die Pluginentwicklung einzusteigen.

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 Hilfsmitteln wie ESLint, Prettier, und SwiftLint. Hier ist eine kurze Übersicht der erforderlichen Formatierungen:

Plugins sollten TypeScript verwenden, um eine bessere Typsicherheit und ES6+-Funktionen wie async/await. Zusätzlich sollten Sie plattform-spezifische 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:

• Use focused interfaces tailored to specific use cases.
• Wenden Sie Unionstypen für plattform-spezifische Variationen an.

Code Dokumentation

Gute Dokumentation ist der Schlüssel, um Ihren Plugin zugänglich und leicht zu verwenden zu machen. Folgen Sie diesen Praktiken:

1. API Dokumentation: 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. Dokumentationsstruktur: Fügen Sie wesentliche Informationen wie Installationsanweisungen, Konfigurationsanweisungen, Plattform-spezifische Anforderungen, Verwendungsexempel und eine detaillierte API-Referenz hinzu.

Eine gut geschriebene Dokumentation stellt sicher, dass Ihr Plugin leicht zu übernehmen und zum breiteren Capacitor-Community beiträgt.

sbb-itb-f9944d2

Leitfaden für die Plugin-Testung

Die Testung von Capacitor-Plugins beinhaltet die Fokussierung auf einige kritische Bereiche, um eine glatte Funktion und Zuverlässigkeit sicherzustellen.

Native Bridge-Tests

Die Überprüfung der Native Bridge stellt sicher, dass es zwischen JavaScript und native code eine ordnungsgemäße Kommunikation 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 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)
}

Sobald Sie bestätigt haben, dass die Kernbrückefunktion wie erwartet funktioniert, wechseln Sie zu der Testung vollständiger Benutzerworkflows.

Vollständige Plugin-Tests

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

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

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

OTA-Test mit Capgo

Capgo's offene Werkzeuge machen es einfach, Updates schnell zu deployen und zu testen. Hier ist, wie Sie es verwenden können:

1. Einstellungen Update-Kanäle wie Entwicklung, Staging und Produktion.
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"
  }
}

Dieser schrittweise Ansatz hilft, Probleme frühzeitig zu erkennen, indem er sich auf Community-Feedback 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 einzureichen:

PR-Einreichungscheckliste

Stellen Sie sicher, dass Sie diese wichtigen Punkte abgedeckt haben, bevor Sie einreichen.

Gemeinschaftsrichtlinien

Wenn man zusammenarbeitet, sollten diese besten Praktiken befolgt werden:

• Respond quickly to reviewer feedback.
• Halten Sie Diskussionen auf technische Details fokussiert.
• Nutzen 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, um automatisierte Überprüfungen durchzuführen, und alle Überprüfungen müssen erfolgreich sein, bevor Ihr Pull-Antrag überprüft werden kann.

Capgo-Integration-Leitfaden

Stellen Sie sicher, dass Ihr Plugin mit Capgo problemlos zusammenarbeitet, bevor Sie es einreichen:

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

2. CI/CD-Integration
   Integriere Capgo in deine CI/CD-Pipeline, um die Update-Deployments zu automatisieren.

3. Update-Monitoring
   Monitor deployment success rates and ensure compliance with app store guidelines.

Zusammenfassung

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

Der PR-Checkliste 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 die Genehmigung durch das App-Store-Team zu veröffentlichen.

Bleiben Sie nach der Merging Ihres Pull Requests engagiert, indem Sie Probleme verfolgen und Versionsupdates freigeben. Regelmäßige Interaktion mit der Community, konsequente Wartung und die Aktualisierung auf Capacitor-Updates sichern, dass Ihr Plugin nützlich und relevant bleibt.

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

Fahren Sie mit der Capacitor-Plugin-Beitragshandlung fort.

Wenn Sie Capgo verwenden Capacitor Plugin Contribution Guide um native Plugin-Arbeit zu planen, verbinden Sie es mit Capgo-Plugin-Beitragshandlung für den Produktworkflow in Capgo Plugin-Verzeichnis Capacitor Plugins durch Capgo zur Implementierungsdetail in Capacitor Plugins durch Capgo Plugins hinzufügen oder aktualisieren zur Implementierungsdetail in Plugins hinzufügen oder aktualisieren Ionische Unternehmens-Plugin-Alternativen für das Produktworkflow in Ionic Enterprise Plugin Alternativen Capgo Native Builds zum Produktworkflow in Capgo Native Builds.