Capacitor Plugin-Beitragshandbuch

Capacitor Plugins verbinden Web-Technologien mit nativen Gerätefunktionen, was die Entwicklung von Apps für mehrere Plattformen ermöglicht. Diese Anleitung hilft Ihnen:

• Deine 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 Fehlerbehandlungen.
• 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.
• Pull-Anfrage einreichen: Stellen Sie sicher, dass die Qualität der code, die Qualität der Tests und die Dokumentation hoch sind, bevor Sie beitragen.

Vollständige Anleitung zur Open-Source-Software - Wie man beiträgt

Einrichtung des Entwicklungsumgebungen

Eine ordnungsgemäße Einrichtung der Entwicklungsumgebung ist für eine effiziente Plugin-Entwicklung 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].

Einrichten des Monorepos

Die Capacitor Plugins Das Ökosystem setzt sich auf eine monorepo-Struktur ab. Diese Vorgehensweise sichert, dass Ihre Arbeit von Anfang an den Gemeinschaftsstandards entspricht.

1. Das Repository fürken und klonen
   Beginnen Sie, indem Sie das Capacitor Plugins-Repository auf GitHub fürken: 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 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 von Native-Plattformen

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

Für iOS:

• Xcode von der Mac App Store herunterladen.

• Install 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) für die Aufrechterhaltung der code Qualität.

Für Android:

• Installieren Sie Android Studio zusammen mit dem neuesten SDK und einer virtuellen Geräteinstellung.
• 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 Plugin-Entwicklung einzusteigen.

Code Standards Guide

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

Richtlinien zur Stilistik

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/await Zusätzlich sollten Sie plattform-spezifische Programmierkonventionen für Swift (iOS) und Kotlin (Android) einhalten.

Fehler- und Typ-Management

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:

• Verwenden Sie fokussierte Interfaces, die auf bestimmte Anwendungsfälle abgestimmt sind.
• Wenden Sie Unionstypen für plattform-spezifische Variationen an.

Code Dokumentation

Ein gutes Dokumentationskonzept ist entscheidend, um Ihren Plugin zugänglich und einfach zu verwenden. 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. README-Struktur: Fügen Sie wichtige Informationen wie Installationsanweisungen, Konfigurationsanweisungen, Plattform-spezifische Anforderungen, Verwendungsexempel und eine detaillierte API-Referenz hinzu.

Ein gut geschriebenes Dokumentationskonzept stellt sicher, dass Ihr Plugin leicht adoptiert werden kann 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 native Bridge-Tests stellen 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.

Ein Beispiel für eine 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 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)
}

Nachdem Sie die Grundfunktion der Bridge bestätigt haben, gehen Sie zur Testung vollständiger Benutzerworkflows über.

Komplette 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 für Geräteinformationen testen, überprüfen Sie:

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

OTA-Testen mit Capgo

Capgo’s offene Quellcode-Tools machen es einfach, Updates schnell zu deployen und zu testen. Hier ist, wie Sie es verwenden können:

1. Einrichtung Update-Kanäle wie Dev, Staging und Produktionsumgebung.
2. Automatisieren Sie die Bereitstellung mit CI/CD-Tools.
3. Aktualisierungen sofort pushen.
4. Leistung und Probleme über das Capgo-Dashboard.

Für phasenweise Bereitstellungen ermöglicht Capgo die Limitierung von Aktualisierungen 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"
  }
}

Diese phasenweise Vorgehensweise hilft, Probleme frühzeitig zu identifizieren, indem sie die Rückmeldung der Community vor einer vollständigen Veröffentlichung nutzen.

Pull-Request-Prozess

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

Überprüfungsliste für die Einreichung eines Pull-Requests

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

- Aktualisieren Sie die README, die Inline-Dokumentation und das CHANGELOG, wenn erforderlich.

Community-Richtlinien

• Wenn man zusammenarbeitet, achten Sie auf diese Best Practices:
• Halten Sie Diskussionen auf technische Details fokussiert.
• Verwenden Sie GitHub’s Vorschlagsfunktion, um code Änderungen vorzuschlagen.
• Stellen Sie kleine, fokussierte Pull-Anfragen ab, 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 von GitHub Actions ab, um automatisierte Überprüfungen durchzuführen, und alle Überprüfungen müssen erfolgreich 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. Versionskontrolle
   Verwenden Sie klare semantische Versionsnummern 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
   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-Stores entsprechen.

Zusammenfassung

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

Der PR-Checkliste unterstreicht die Bedeutung von hochwertigen Einreichungen. 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.

Sobald Ihr PR eingereicht wurde, bleibt Ihr Beitrag aktiv, indem Sie sich an den Problemen beteiligen und Versionen aktualisieren. Regelmäßige Interaktion mit der Gemeinschaft, konsistente Wartung und die Aktualisierung auf Capacitor-Updates stellen sicher, dass Ihr Plugin nützlich und relevant bleibt.

Achten Sie auf Benutzerfeedback und aktualisieren Sie Ihr Plugin entsprechend. Dieser ständige Aufwand hilft dabei, die Gesamtklasse des Ökosystems aufrechtzuerhalten und Ihr Plugin für Entwickler wertvoll zu machen.

Fortsetzen Sie mit der Anleitung zum Beitrag von Capacitor-Plugins

Wenn Sie "__CAPGO_KEEP_0__-Plugin-Beitrag-Anleitung" verwenden, um native Plugin-Arbeiten zu planen, verbinden Sie sie mit "__CAPGO_KEEP_0__-Plugin-Verzeichnis" Capacitor Plugin Contribution Guide Um mit Ihrem Plugin einen wertvollen Beitrag zu leisten, ist es wichtig, sich an den etablierten Prozess zu halten und die Gemeinschaftsstandards einzuhalten. Dazu gehört, sich an die Richtlinien von __CAPGO_KEEP_0__ für die Programmierung zu halten und Ihr Werk gründlich zu testen. Der PR-Checkliste unterstreicht die Bedeutung von hochwertigen Einreichungen. 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. für den Produktworkflow in Capgo Plugin-Verzeichnis Capacitor Plugins von Capgo für die Implementierungsdetails in Capacitor Plugins von Capgo, Hinzufügen oder Aktualisieren von Plugins für die Implementierungsdetails in Hinzufügen oder Aktualisieren von Plugins, Ionic Enterprise-Plugin-Alternativen für den Produktworkflow in Ionic Enterprise-Plugin-Alternativen, und Capgo Native Builds für den Produktworkflow in Capgo Native Builds.