Capacitor プラグインコントリビューションガイド

Capacitor プラグインはWeb技術とネイティブデバイスの機能を連携させ、クロスプラットフォームなアプリ開発を可能にします。このガイドでは以下について説明します：

開発環境のセットアップ：以下のツールなど Node.js, Xcodeや Android Studio が不可欠です。
Code 標準に従ってください: 使用する TypeScript, Swiftや Kotlin を用い、命名規則とエラーハンドリングを統一してください。
徹底的にテストする: JavaScript、iOS、Android のユニットテストを記述し、信頼性を確保してください。
明確なドキュメント作成: JSDoc や README を活用し、導入しやすくしてください。
プルリクエストの送信: コントリビュートする前に、高品質な code、テスト、およびドキュメントを準備してください。

オープンソース完全ガイド - コントリビューションの方法

開発環境のセットアップ

効率的なプラグイン開発には、適切な開発環境の構築が不可欠です。環境が整っていれば、コーディング、テスト、プラグインのデプロイをスムーズに行えます。

必要なツールとスキル

開始する前に、以下のツールがインストールされていることを確認してください：

カテゴリー	要件
主要ツール	Node.js (LTS), npm 6+, Git
IDE/エディタ	Visual Studio Code またはお好みのエディタ
iOS開発	Xcode, SwiftLint, CocoaPods
Android開発	Android Studio、Android SDK、JDK

Web開発のためのTypeScript、およびネイティブ開発のためのSwift (iOS) または Java/Kotlin (Android) の知識が必要です。 [1][2].

モノレポのセットアップ

この Capacitor プラグインエコシステムはモノレポ構造を採用しています。この手法により、最初からコミュニティ標準に沿った開発が可能になります。

リポジトリのフォークとクローン
GitHub 上にある Capacitor plugins リポジトリをフォークすることから始めます。その後、フォークしたリポジトリをクローンしてください：
```
git clone https://github.com/your-username/capacitor-plugins.git
cd capacitor-plugins
npm install
```
依存関係のインストールとビルド
以下のコマンドを実行して、必要なパッケージのインストールとプラグインのビルドを行います：
```
npm run build
```
バージョン管理の設定
変更にはフィーチャーブランチを使用し、フォークしたリポジトリを常にアップストリームのリポジトリと同期させておいてください。

Nativeプラットフォームの準備

クロスプラットフォーム開発には、iOSとAndroid両方の環境設定が必要です。

iOSの場合:

Mac App StoreからXcodeをダウンロードしてください。
以下のコマンドでコマンドラインツールをインストールします:
```
xcode-select --install
```
以下のコマンドでCocoaPodsをインストールします:
```
sudo gem install cocoapods
```
Apple Developerアカウントと必要な証明書をセットアップしてください。
codeの品質を維持するためにSwiftLint（任意）を使用します。

Androidの場合:

Android Studioと最新のSDK、および仮想デバイスをインストールしてください。
JDKがインストールされていることを確認してください。
Android Studio内でAndroid SDKを適切に設定してください。

これらのプラットフォームをセットアップすれば、確立されたコーディングプラクティスに従ってプラグイン開発に取り組む準備が整います。

Code 標準ガイド

開発環境が整ったら、メンテナンスしやすく使いやすいプラグインを構築するため、以下のガイドラインに従ってください。

スタイルガイドへの準拠

この Capacitor プラグインエコシステム次のようなツールを使って厳格なコーディング規約を適用しています： ESLint, Prettier、および SwiftLint。必須フォーマットの概要は次のとおりです：

コンポーネント	フォーマット
変数	`deviceInfo` (camelCase)
クラス	`BatteryManager` (PascalCase)
メソッド	`getLanguageCode()` (camelCase)
定数	`MAX_RETRY_COUNT` (SNAKE_CASE)

型安全性を高め、ES6+の機能を活用するために、プラグインにはTypeScriptを使用してください。また、 async/awaitSwift (iOS) や Kotlin (Android) のプラットフォーム固有のコーディング規約に従ってください。

エラーと型の管理

クロスプラットフォームでの互換性を保つには、一貫したエラーハンドリングが不可欠です。以下に例を示します。

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

型安全性を確保するために:

特定のユースケースに合わせた、特化したインターフェースを使用してください。
プラットフォーム固有のバリエーションには、Union Typesを適用してください。

Code ドキュメント

優れたドキュメントは、プラグインのアクセシビリティと使いやすさを向上させる鍵となります。以下のプラクティスに従ってください:

API ドキュメント: 次のツールと連携するJSDocコメントを記述してください: @capacitor/docgen例:

/**
 * @description Get the device's current battery level
 * @returns Promise with the battery level percentage
 */
async getBatteryLevel(): Promise<{ level: number }>;

READMEの構成: インストール手順、設定方法、プラットフォームごとの要件、使用例、および詳細な API リファレンスなどの必須情報を含めてください。

ドキュメントが充実していれば、プラグインの導入が容易になり、より広範な Capacitor コミュニティへの貢献につながります。

sbb-itb-f9944d2

プラグインのテストガイド

Capacitor プラグインのテストでは、スムーズな動作と信頼性を確保するために、いくつかの重要な領域に焦点を当てる必要があります。

ネイティブブリッジのテスト

ネイティブブリッジのテストは、JavaScript とネイティブの code との間の通信が正しく行われているかを確認するものです。まずは、各プラットフォームに最適化されたフレームワークを使用してテスト環境を構築しましょう。

以下は、 Jest を使用した JavaScript 側のユニットテストの例です：

// 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);
  });
});

ネイティブ側のテストには、iOS では XCTest、Android では JUnit を使用します。以下は Android の例です：

@Test
fun testBatteryLevel() {
    val plugin = DeviceInfo()
    val result = plugin.getBatteryLevel()
    assertTrue(result.level in 0..100)
}

コアとなるブリッジ機能が期待通りに動作することを確認したら、次は一連のユーザーワークフローのテストに進みます。

プラグインの総合テスト

プラグインがさまざまなシナリオで適切に動作することを確認するために、以下のカテゴリごとにテストを行ってください：

テストカテゴリ	重点領域
統合テスト	クロスプラットフォーム機能
パフォーマンステスト	リソース使用量とレスポンスタイム
セキュリティテスト	データ処理と権限チェック

複雑な機能を持つプラグインの場合は、実際のユーザーシナリオをシミュレートしてください。例えば、DeviceInfoプラグインをテストする場合は、以下を確認します：

異なるネットワーク条件下でのアップロード成功
正確な進捗レポート
大容量ファイル転送中のメモリ使用量

OTA Testing with Capgo

Capgo Live Update ダッシュボードインターフェース

Capgoのオープンソースツールを使えば、アップデートのデプロイとテストを迅速に行えます。使い方は以下の通りです：

セットアップアップデートチャネル（dev、staging、productionなど）の設定。
CI/CDツールでデプロイを自動化。
アップデートを即座に配信。
パフォーマンスや問題の監視は、 Capgo dashboardから行えます。.

段階的なロールアウトには、Capgoでアップデート対象を少数のユーザーに限定できます。例えば、24時間ごとにユーザーの25%ずつに新バージョンを公開するといった運用が可能です：

// Example configuration for staged rollout
{
  "plugin": "camera-plugin",
  "version": "1.2.0",
  "rollout": {
    "percentage": 25,
    "interval": "24h"
  }
}

この段階的なアプローチにより、フルリリース前にコミュニティからのフィードバックを活用して、問題を早期に特定できます。

Pull Request のプロセス

変更内容のテストが完了したら、以下の手順で Pull Request を送信してください：

PR 送信時のチェックリスト

送信前に、以下の主要な項目を確認してください：

カテゴリ	確認事項
Code の品質	- Swift/Kotlin の実装が Web 版の API と一致していることを確認してください。
テスト	- 新しい機能にはユニットテストを追加してください。 - CI/CD パイプラインのチェックが成功することを確認してください。
ドキュメント	- 必要に応じてREADME、インラインドキュメント、CHANGELOGを更新してください。

コミュニティガイドライン

コラボレーションの際は、以下のベストプラクティスに従ってください：

レビュアーからのフィードバックには迅速に回答してください。
議論は技術的な詳細に集中させてください。
code の変更を提案する場合は、GitHub の suggestion 機能を使用してください。
一度に一つの機能や問題に対処する、小さくまとまったプルリクエストを送信してください。

大規模な変更を行う場合は、まず issue を作成してアプローチを相談することをお勧めします。Capacitor チームは自動チェックに GitHub Actions を利用しており、プルリクエストのレビュー前にすべてのチェックをパスする必要があります。

Capgo 連携ガイド

プラグインに Live Update が関わる場合は、提出前に Capgo とシームレスに動作することを確認してください：

バージョン管理
プラグインには明確なセマンティックバージョニングを使用し、すべての変更を changelog に記録してください。Capgo のシステムは、ユーザーデバイス間でのバージョン採用状況の追跡を支援します。
CI/CD 連携
Capgo を CI/CD パイプラインに組み込んで、アップデートのデプロイを自動化しましょう。
アップデートのモニタリング
デプロイの成功率を監視し、App Store のガイドラインに準拠していることを確認します。

まとめ

プラグインで価値のある貢献をするには、確立されたプロセスに従い、コミュニティ基準を満たすことが重要です。これには、Capacitor のコーディングガイドラインの遵守や、徹底したテストが含まれます。

PR チェックリストは、高品質な提出が必要であることを示しています。もしプラグインが Live Update をサポートしているなら、(前述のように) Capgo と連携させることで、App Store の承認を待たずに迅速にアップデートをリリースできます。

PR がマージされた後は、Issue の追跡やバージョン更新を通じて継続的に関わりましょう。コミュニティとの定期的な交流や継続的なメンテナンス、そして Capacitor のアップデートへの追従が、プラグインの有用性と関連性を維持する鍵となります。

ユーザーのフィードバックに注意を払い、必要に応じてアップデートを行ってください。この継続的な取り組みが、エコシステム全体の品質を維持し、開発者にとって価値のあるプラグインであり続けることにつながります。

Capacitor プラグイン貢献ガイドへ戻る

使用している場合 Capacitor プラグインコントリビューションガイド ネイティブプラグインの作業を計画するには、次と連携してください： Capgo プラグインディレクトリ Capgo プラグインディレクトリのプロダクトワークフローについては、 Capgo による Capacitor プラグイン Capgo による Capacitor プラグインの実装詳細については、プラグインの追加または更新プラグインの追加または更新に関する実装詳細については、 Ionic Enterprise プラグインの代替案 Ionic Enterprise Plugin Alternatives のプロダクトワークフロー、および Capgo Native Build Capgo Native Builds のプロダクトワークフローについては、