Capacitor プラグイン貢献ガイド

Capacitor プラグインは、ウェブテクノロジーをネイティブデバイス機能と接続し、クロスプラットフォームアプリ開発を可能にします。このガイドは、あなたを助けます：

環境を設定する: Node.js、Xcode、および Android Studio のようなツールは必須です。
コードスタンダードに従う: 一貫した命名規則とエラーハンドリングを使用して、TypeScript、Swift、および Kotlinを使用してください。
徹底的にテストする: JavaScript、iOS、およびAndroidのユニットテストを書いて、信頼性を確保してください。
明確に文書化する: 簡単に採用できるようにJSDocとREADMEファイルを使用してください。
プルリクエストを提出する: 貢献する前に、高品質のコード、テスト、ドキュメンテーションを確保してください。

オープンソースの完全ガイド - どのように貢献するか

開発環境の設定

適切な開発環境を作成することは、効率的なプラグイン開発の鍵です。整ったセットアップにより、プラグインのコーディング、テスト、デプロイがスムーズに行えます。

必要なツールとスキル

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

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

ウェブ開発にはTypeScriptに慣れ、ネイティブ開発タスクにはSwift（iOS用）またはJava/Kotlin（Android用）にも慣れておく必要があります [1][2]。

モノレポの設定

Capacitorプラグインエコシステムはモノレポ構造に依存しています。このアプローチにより、作業がコミュニティスタンダードに初めから整合することが保証されます。

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

ネイティブプラットフォームの準備

クロスプラットフォーム開発には、iOS環境とAndroid環境の両方を構成する必要があります。

iOSの場合：

Mac App StoreからXcodeをダウンロードします。
次のコマンドを使用してコマンドラインツールをインストールします：
Terminal window
```
xcode-select --install
```
次のコマンドでCocoaPodsをインストールします：
Terminal window
```
sudo gem install cocoapods
```
Apple Developerアカウントと必要な証明書を設定します。
コード品質を維持するためにSwiftLintを使用します（オプション）。

Androidの場合：

Android Studioを最新のSDKおよび仮想デバイスと共にインストールします。
JDKがインストールされていることを確認します。
Android Studio内でAndroid SDKを適切に構成します。

これらのプラットフォームが設定されたら、確立されたコーディングプラクティスに従ってプラグイン開発に取り組むことができます。

コードスタンダードガイド

開発環境が設定されたら、メンテナンスしやすく使用しやすいプラグインを作成するために、これらのガイドラインに従ってください。

スタイルガイドの遵守

Capacitorプラグインエコシステムは、ESLint、Prettier、およびSwiftLintのようなツールを使用して厳格なコーディングスタンダードを遵守しています。必要なフォーマットの簡単な概要は以下の通りです：

コンポーネント	フォーマット
変数	`deviceInfo` (キャメルケース)
クラス	`BatteryManager` (パスカルケース)
メソッド	`getLanguageCode()` (キャメルケース)
定数	`MAX_RETRY_COUNT` (スネークケース)

プラグインは、TypeScriptを使用してより良い型安全性とES6+の機能（async/awaitなど）を利用する必要があります。さらに、Swift（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}`);
  }
}

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

特定のユースケースに合わせたフォーカスされたインターフェースを使用します。
プラットフォーム固有の変種にはユニオン型を適用します。
実行時に型を検証するために型ガードを実装します [1]。

コード文書化

良いドキュメントは、プラグインをアクセスしやすくし、使いやすくするための鍵です。これらの実践に従ってください：

APIドキュメンテーション: @capacitor/docgenで動作するJSDocコメントを書きます。例：

/**
 * @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とネイティブコード間の適切な通信を保証します。始めるには、各プラットフォームに特化したフレームワークでテスト環境を設定します。

以下はJavaScript側のJestユニットテストの例です：

// 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プラグインをテストしている場合、次の内容を確認してください：

異なるネットワーク条件でのアップロード成功
正確な進行状況の報告
大きなファイル転送中のメモリ使用量

Capgoを使用したOTAテスト

Capgo

Capgoのオープンソースツールを使用することで、迅速に更新をデプロイおよびテストできます。使用方法は以下の通りです：

dev、staging、およびproductionのような更新チャンネルを設定します。
CI/CDツールを使用してデプロイを自動化します。
更新を即座にプッシュします。
Capgoダッシュボードを介して性能と問題を監視します。

段階的なロールアウトの場合、Capgoでは更新を少数のユーザーに制限できます。たとえば、24時間ごとに25％のユーザーに新しいバージョンを展開できます：

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

この段階的アプローチは、完全なリリースの前にコミュニティのフィードバックを活用して早期に問題を特定するのに役立ちます。

プルリクエストプロセス

変更を徹底的にテストしたら、プルリクエストを提出するためにこれらのステップに従ってください：

PR提出チェックリスト

提出前に、以下の主要な領域がカバーされていることを確認してください：

カテゴリ	チェック内容
コード品質	- Swift/Kotlinの実装がウェブAPIと一致していることを確認します。
テスト	- 新しい機能に対してユニットテストを追加します。 - CI/CDパイプラインチェックが成功していることを確認します。
ドキュメンテーション	- README、インラインドキュメント、およびCHANGELOGを必要に応じて更新します。

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

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

レビュアーのフィードバックに迅速に対応します。
討論を技術的な詳細に集中させます。
GitHubの提案機能を使用してコードの変更を提案します。
一度に1つの機能または問題に対処する小規模で集中したプルリクエストを提出します。

大きな変更の場合、最初にイシューを作成し、アプローチについて話し合うのが良いアイデアです。Capacitorチームは自動チェックのためにGitHub Actionsを利用し、すべてのチェックが通過する必要があります。

Capgo統合ガイド

プラグインにライブ更新が含まれる場合、提出前にCapgoとシームレスに連携していることを確認してください：

バージョン管理
プラグインに対して明確なセマンティックバージョニングを使用し、変更をすべてCHANGELOGに文書化します。Capgoのシステムは、ユーザーのデバイス間でのバージョンの採用を追跡するのに役立ちます。
CI/CD統合
CI/CDパイプラインにCapgoを統合して、更新のデプロイを自動化します。
更新モニタリング
デプロイの成功率を監視し、アプリストアのガイドラインに準拠することを確認します。

まとめ

プラグインで意義のある貢献をするためには、確立されたプロセスに従い、コミュニティスタンダードを満たすことが重要です。これには、Capacitorのコーディングガイドラインに従い、作業を徹底的にテストすることが含まれます。

PRチェックリストは、高品質の提出が必要であることを強調しています。プラグインがライブ更新をサポートしている場合、先に述べたようにCapgoと統合することで、アプリストアの承認を待たずに迅速に更新をリリースできます。

PRがマージされたら、問題を追跡し、バージョンの更新をリリースすることで関与し続けてください。コミュニティとの定期的な交流、一貫したメンテナンス、およびCapacitorの更新を追跡することは、プラグインが役立ち続け、関連性を保つことを保証します。

ユーザーフィードバックに注意を払い、必要に応じて更新を行ってください。この継続的な努力はエコシステムの全体的な質を維持し、開発者にとってあなたのプラグインを価値あるものに保つのに役立ちます。