Capacitor Plugin Contribution Guide

Capacitor Plugins verbinden Web-Technologien mit nativen Device-Features, was Cross-Platform App Developmentermöglicht. Dieser Guide hilft dir:

• Deine Umgebung einrichten: Tools wie Node.js, Xcode, und Android Studio sind unverzichtbar.
• Folge den Code Standards: Nutze TypeScript, Swift, und Kotlin mit einheitlichen Namenskonventionen und Error Handling.
• Gründlich testen: Schreibe Unit-Tests für JavaScript, iOS und Android, um Zuverlässigkeit zu garantieren.
• Klar dokumentieren: Nutze JSDoc und README-Dateien für eine einfache Integration.
• Pull Request einreichen: Achte auf hochwertige code, Tests und Dokumentation vor dem Contribute.

Open Source Guide – So leistest du einen Beitrag

Setup der Entwicklungsumgebung

Eine ordnungsgemäße Entwicklungsumgebung ist der Schlüssel zu einer effizienten Plugin-Entwicklung. Ein gut vorbereitetes Setup ermöglicht reibungsloses Coding, Testing und Deployment deiner Plugins.

Benötigte Tools und Skills

Stelle vor dem Start sicher, dass du folgende Tools installiert hast:

Zudem solltest du sicher im Umgang mit TypeScript für die Webentwicklung sein sowie Swift (für iOS) oder Java/Kotlin (für Android) für native Entwicklungsaufgaben beherrschen. [1][2].

Das Monorepo einrichten

Die Capacitor Plugin installierst, Das Ökosystem basiert auf einer Monorepo-Struktur. Dieser Ansatz stellt sicher, dass deine Arbeit von Anfang an den Community-Standards entspricht.

1. Repository forken und clonen
   Forke zuerst das Capacitor Plugins-Repository auf GitHub. Klonen Sie anschließend dein geforktes Repository:

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

2. Dependencies installieren und Build ausführen
   Führe den folgenden Befehl aus, um alles Notwendige zu installieren und die Plugins zu bauen:

   npm run build

3. Versionsverwaltung einrichten
   Nutze Feature-Branches für deine Änderungen und halte deinen Fork mit dem Upstream-Repository synchron.

Native Plattformen vorbereiten

Für die Cross-Platform-Entwicklung musst du sowohl die iOS- als auch die Android-Umgebung konfigurieren.

Für iOS:

• Lade Xcode aus dem Mac App Store herunter.

• Installiere die Command-Line Tools mit:

  xcode-select --install

• Installiere CocoaPods mit:

  sudo gem install cocoapods

• Richte einen Apple Developer Account und die benötigten Zertifikate ein.

• Nutze SwiftLint (optional), um die code-Qualität beizubehalten.

Für Android:

• Installiere Android Studio zusammen mit dem neuesten SDK und einem virtuellen Gerät.
• Stelle sicher, dass ein JDK installiert ist.
• Konfiguriere das Android SDK korrekt in Android Studio.

Sobald diese Plattformen eingerichtet sind, kannst du bewährte Coding-Praktiken anwenden und direkt mit der Plugin-Entwicklung starten.

Code Standards-Leitfaden

Nachdem deine Entwicklungsumgebung nun bereitsteht, solltest du dich an diese Richtlinien halten, um Plugins zu entwickeln, die einfach zu warten und zu nutzen sind.

Einhaltung des Style Guides

Die Capacitor Plugin-Ökosystem erzwingt strikte Coding-Standards mit Tools wie ESLint, Prettier, und SwiftLint. Hier ist ein kurzer Überblick über die erforderliche Formatierung:

Plugins sollten TypeScript für bessere Typsicherheit und ES6+-Features wie zum Beispiel nutzen async/await. Beachte zudem die plattformspezifischen Coding-Conventions für Swift (iOS) und Kotlin (Android).

Error- und Type-Management

Ein konsistentes Error-Handling ist entscheidend für die Cross-Platform-Kompatibilität. Hier 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 Typsicherheit:

• Nutze fokussierte Interfaces, die auf spezifische Use Cases zugeschnitten sind.
• Verwende Union Types für plattformspezifische Variationen.

Code Dokumentation

Gute Dokumentation ist entscheidend, damit dein Plugin zugänglich und einfach zu nutzen ist. Halte dich an diese Best Practices:

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: Füge essenzielle Infos wie Installationsschritte, Konfiguration, plattformspezifische Anforderungen, Code-Beispiele und eine detaillierte API Referenz hinzu.

Eine gute Dokumentation sorgt für eine schnelle Adoption deines Plugins und stärkt die gesamte Capacitor Community.

sbb-itb-f9944d2

Leitfaden zum Plugin-Testing

Beim Testen von Capacitor Plugins liegt der Fokus auf einigen kritischen Bereichen, um reibungslose Funktionalität und Zuverlässigkeit zu garantieren.

Native Bridge Tests

Tests der Native Bridge stellen die korrekte Kommunikation zwischen JavaScript und dem nativen code sicher. Richte dazu deine Testumgebung mit Frameworks ein, die auf die jeweilige Plattform zugeschnitten sind.

Hier ist ein Beispiel für einen Jest Unit Test 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 Tests auf der nativen Seite verwende 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 die Kernfunktionalität der Bridge wie erwartet läuft, solltest du die vollständigen User Workflows testen.

Vollständige Plugin-Tests

Um sicherzustellen, dass dein Plugin in verschiedenen Szenarien performant läuft, teste verschiedene Kategorien:

Simuliere bei Plugins mit komplexen Funktionen reale Anwendungsfälle. Wenn du zum Beispiel ein DeviceInfo-Plugin testest, prüfe Folgendes:

• Erfolgreiche Uploads unter verschiedenen Netzwerkbedingungen
• Präzise Fortschrittsanzeige
• Speicherverbrauch bei großen Dateiübertragungen

OTA-Testing mit Capgo

Mit den Open-Source-Tools von Capgo lassen sich Updates schnell deployen und testen. So geht's:

1. Richten Sie Update-Channels wie dev, staging und production.
2. Automatisiere Deployments mit CI/CD-Tools.
3. Updates sofort pushen.
4. Überwache Performance und Issues über das Capgo Dashboard.

Für Phased Rollouts kannst du mit Capgo Updates auf einen kleinen Prozentsatz der User begrenzen. Zum Beispiel kannst du alle 24 Stunden eine neue Version an 25 % der User 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 durch Community-Feedback vor dem Full Release zu identifizieren.

Pull Request Prozess

Sobald du deine Änderungen gründlich getestet hast, folge diesen Schritten, um deinen Pull Request einzureichen:

Checkliste für PR-Submissions

Stelle vor dem Absenden sicher, dass du diese Kernbereiche abgedeckt hast:

Community-Richtlinien

Halte dich bei der Zusammenarbeit an diese Best Practices:

• Reagiere zeitnah auf Feedback der Reviewer.
• Konzentriere dich in Diskussionen auf technische Details.
• Nutze die Vorschlagsfunktion von GitHub, um Änderungen an code vorzuschlagen.
• Reiche kleine, fokussierte Pull Requests ein, die jeweils nur ein Feature oder Problem lösen.

Erstelle bei größeren Änderungen am besten zuerst ein Issue, um deinen Ansatz zu besprechen. Das Team von Capacitor nutzt GitHub Actions für automatisierte Checks, und alle Checks müssen bestanden sein, bevor dein Pull Request geprüft werden kann.

Capgo Integrationsguide

Falls dein Plugin Live Updates nutzt, stelle sicher, dass es reibungslos mit Capgo funktioniert, bevor du es einreichst:

1. Versionskontrolle
   Nutze eindeutiges Semantic Versioning für dein Plugin und dokumentiere alle Änderungen im Changelog. Das System von Capgo hilft dabei, die Versionsverteilung auf den Geräten der Nutzer zu tracken.

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

3. Update-Monitoring
   Überwache die Erfolgsraten der Deployments und stelle die Einhaltung der App Store Guidelines sicher.

Zusammenfassung

Um mit deinem Plugin einen echten Mehrwert zu bieten, ist es wichtig, den etablierten Prozess zu befolgen und Community-Standards einzuhalten. Dazu gehört die Einhaltung der Coding-Guidelines von Capacitor sowie gründliches Testen deiner Arbeit.

Die PR-Checkliste unterstreicht die Notwendigkeit hochwertiger Submissions. Wenn dein Plugin Live Updates unterstützt, hilft dir die Integration in Capgo (wie bereits erwähnt), Updates schnell zu veröffentlichen, ohne auf App-Store-Freigaben zu warten.

Sobald dein PR gemerged wurde, bleib aktiv, indem du Issues trackst und neue Versionen veröffentlichst. Regelmäßiger Austausch mit der Community, kontinuierliche Wartung und mit den Updates von Capacitor Schritt zu halten sorgen dafür, dass dein Plugin nützlich und relevant bleibt.

Achte auf User-Feedback und veröffentliche bei Bedarf Updates. Dieser kontinuierliche Einsatz hilft, die Qualität des gesamten Ökosystems zu sichern und dein Plugin für Entwickler wertvoll zu halten.

Weiter mit dem Capacitor Plugin Contribution Guide

Wenn Sie ... verwenden Capacitor Plugin Contribution Guide um die Arbeit an Native Plugins zu planen, verbinde es mit Capgo Plugin-Verzeichnis für den Produkt-Workflow im Capgo Plugin-Verzeichnis, Capacitor Plugins von Capgo für die Implementierungsdetails in Capacitor Plugins von Capgo, Plugins hinzufügen oder aktualisieren für die Implementierungsdetails in Adding or Updating Plugins, Ionic Enterprise Plugin-Alternativen für den Produkt-Workflow in Ionic Enterprise Plugin Alternatives und Capgo Native Builds für den Produkt-Workflow in Capgo Native Builds.