Capacitor プラグイン貢献ガイド

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

環境をセットアップする： Node.js, Xcode、 Android Studio は不可欠です。
Code の標準を遵守してください: TypeScript, Swift、 Kotlin に一貫した命名規則とエラー処理を使用してください。
徹底的にテストしてください：
JavaScript、iOS、Android用のユニットテストを書いて、信頼性を確保してください。明確にドキュメントしてください：
Pull リクエストを提出する: 高品質な code, テスト、ドキュメントを確保することを確認してください。

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

開発環境の設定

適切な開発環境の作成は、効率的なプラグイン開発の鍵です。ご準備が整った設定により、スムーズなコーディング、テスト、デプロイが可能になります。

必要なツールとスキル

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

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

Web開発ではTypeScriptに慣れており、iOSではSwift、AndroidではJavaまたはKotlinに慣れていることが望ましい [1][2].

Monorepoの設定

The Capacitor プラグインこのエコシステムは、モノレポ構造に依存しています。このアプローチにより、コミュニティの標準に沿った作業がすぐに始まります。

リポジトリをフォークしてクローンする
Capacitor プラグインリポジトリを GitHub にフォークしてから、フォークしたリポジトリをクローンしてください。
```
git clone https://github.com/your-username/capacitor-plugins.git
cd capacitor-plugins
npm install
```
依存関係をインストールしてビルド
必要なすべてのものをインストールしてプラグインをビルドするために、以下のコマンドを実行してください。
```
npm run build
```
バージョン管理を設定する
変更を特定の機能ブランチで行い、上流リポジトリとフォークを同期してください。

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

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

iOS:

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

Androidの場合:

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

プラットフォームが設定されたら、既存のコーディング慣習に従い、プラグイン開発に進む準備が整います。

Code スタンダードガイド

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

スタイルガイドコンプライアンス

The Capacitor plugin ecosystem 厳格なコーディング規範を強制するツールとして ESLint, Prettier、SwiftLint

を使用します。ここでは、必要なフォーマットの簡単な概要を紹介します。	コンポーネント
フォーマット	`deviceInfo` 変数
(キャメルケース)	`BatteryManager` クラス名(パスカルケース)
メソッド	`getLanguageCode()` (キャメルケース)
定数	`MAX_RETRY_COUNT` (スネークケース)

プラグインは、より良い型安全性とES6+機能を利用するためにTypeScriptを使用する必要があります。例えば、Swift(iOS)とKotlin(Android)のプラットフォーム固有のコーディング規約を遵守する必要があります。 async/awaitエラーと型の管理

クロスプラットフォーム互換性のために一貫したエラーハンドリングが重要です。ここでは例を示します。

型の安全性のために:

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

特定の用途に合わせたフォーカスされたインターフェイスを使用する。

プラットフォーム固有のバリエーションに対してユニオン型を適用する。
__CAPGO_KEEP_0__ ドキュメント

Code Documentation

ドキュメントの作成は、プラグインのアクセス性と使いやすさを高めるために重要です。以下の慣行に従ってください。

API ドキュメントJSDocコメントの書き方 @capacitor/docgenJSDocコメントは、以下の例のように機能するように書きましょう。

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

READMEの構造READMEには、インストールの手順、設定の指示、プラットフォーム固有の要件、使用例、および詳細なAPIリファレンスが含まれます。

ドキュメントの書き方が良くなることで、プラグインの採用が容易になり、より広範なCapacitorコミュニティに貢献することができます。

sbb-itb-f9944d2

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

Capacitor プラグインのテストには、機能性と信頼性を確保するために、重要な幾つかの領域に焦点を当てて、順調な動作を確保する必要があります。

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

ネイティブブリッジテストは、JavaScriptとネイティブcode間の適切なコミュニケーションを確保するために必要です。始めるには、各プラットフォームに特化したフレームワークを使用して、テスト環境を設定してください。

Capgoの例 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)
}

コアブリッジの基本的な機能が期待どおりに動作することを確認したら、ユーザーフローの完全なワークフローをテストするまで進みます。

プラグインテスト

プラグインがさまざまなシナリオで良好に動作することを確認するには、さまざまなカテゴリをテストする必要があります。

テストカテゴリ	主な焦点領域
統合テスト	クロスプラットフォーム機能
パフォーマンステスト	リソース使用量と応答時間
セキュリティテスト	データ処理と権限チェック

複雑な機能を持つプラグインの場合、実世界のユーザーシナリオをシミュレートします。例えば、デバイス情報プラグインをテストする場合、次のことを確認します:

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

OTAテスト Capgo

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

Capgoのオープンソースツールは、迅速にアップデートを展開およびテストすることを容易にします。ここでは、それを使用する方法を紹介します:

セットアップアップデートチャンネル dev、ステージング、およびプロダクションなどのように
CI/CDツールを使用してデプロイを自動化する
即時更新
パフォーマンスと問題を「__CAPGO_KEEP_0__ ダッシュボード」経由で監視するフェーズドロールアウトの場合、「Capgo」は、更新を少数のユーザーに制限することを許可します。たとえば、24時間ごとに25%のユーザーに新しいバージョンをロールアウトできます:.

For phased rollouts, Capgo allows you to limit updates to a small percentage of users. For instance, you can roll out a new version to 25% of users every 24 hours:

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

プルリクエストプロセス

変更を徹底的にテストした後、次の手順に従ってプルリクエストを提出する

PR 提出チェックリスト

提出する前に、次の重要な領域をカバーすることを確認する

Pull Request Process

カテゴリ	確認するもの
Code 品質	- Swift/Kotlin の実装がウェブ API と一致することを確認する。
テスト	- 新機能のユニットテストを追加する。 - CI/CD パイプラインのチェックが正常に実行されることを確認する。
ドキュメント	- README、インラインドキュメント、および CHANGELOG を必要に応じて更新する。

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

協力する際は、以下のベストプラクティスに従う。

レビューフィードバックに迅速に対応する。
技術的な詳細に焦点を当てた議論を維持してください。
GitHubの提案機能を使用して、codeの変更を提案してください。
1つの機能または問題に対して、時期を節約して小さく集中したプルリクエストを提出してください。

より大きな変更の場合、まず問題を作成し、取り組み方について議論することが良いでしょう。Capacitorチームは、GitHubアクションに依存しており、すべてのチェックが通過するまでプルリクエストがレビューされることはありません。

Capgo統合ガイド

ライブ更新が含まれるプラグインの場合、Capgoと互換性のあるように動作することを確認し、提出する前に確認してください。

バージョン管理
プラグインのバージョン管理に明確な意味論的バージョニングを使用し、すべての変更を変更履歴に記録してください。Capgoのシステムは、ユーザー端末のデバイス間でバージョン採用を追跡するのに役立ちます。
CI/CD統合
CapgoをCI/CDパイプラインに統合して、更新の自動展開を実行してください。
更新監視
展開成功率を監視し、アプリストアのガイドラインに準拠することを確認してください。

Summary

To make a meaningful contribution with your plugin, it’s important to follow the established process and meet community standards. This includes sticking to Capacitor’s coding guidelines and thoroughly testing your work.

The PR checklist highlights the need for high-quality submissions. If your plugin supports live updates, integrating with Capgo (as mentioned earlier) can help you release updates quickly without waiting for app store approvals.

Once your PR is merged, stay involved by tracking issues and releasing version updates. Regular interaction with the community, consistent maintenance, and keeping up with Capacitor updates will ensure your plugin stays useful and relevant.

Pay attention to user feedback and make updates as needed. This ongoing effort helps maintain the overall quality of the ecosystem and keeps your plugin valuable for developers.

Keep going from Capacitor Plugin Contribution Guide

If you are using Capacitor Plugin Contribution Guide to plan native plugin work, connect it with Capgo Plugin Directory 製品ワークフローについての情報は、Capgo プラグインディレクトリで確認できます。 Capacitor プラグインは、Capgo によって提供されています。 for the implementation detail in Capacitor Plugins by Capgo, プラグインの追加または更新実装の詳細についての情報は、プラグインの追加または更新で確認できます。 Ionic Enterprise プラグインの代替製品ワークフローについての情報は、Ionic Enterprise プラグインの代替で確認できます。 Capgo ネイティブビルド製品ワークフローについての情報は、Capgo ネイティブビルドで確認できます。

Capacitor プラグインの貢献ガイド