Capacitor Panduan Kontribusi Plugin

Capacitor menghubungkan teknologi web dengan fitur perangkat native, memungkinkan pengembangan aplikasi lintas platform. Panduan ini membantu Anda:

• Siapkan Lingkungan Anda: Alat seperti Node.js, Xcode, dan Android Studio merupakan hal yang sangat penting.
• Ikuti Code Standar: Gunakan TypeScript, Swift, dan Kotlin dengan konvensi penamaan yang konsisten dan pengelolaan kesalahan.
• Tes Secara Teliti: Tuliskan unit tes untuk JavaScript, iOS, dan Android untuk memastikan keandalan.
• Dokumentasikan Jelas: Gunakan JSDoc dan file README untuk pengadopsian yang mudah.
• Kirimkan Permintaan Pull: Pastikan kualitas code, pengujian, dan dokumentasi tinggi sebelum berkontribusi.

Petunjuk Lengkap untuk Sumber Terbuka - Bagaimana Berkontribusi

Pengaturan Lingkungan Pengembangan

Membuat lingkungan pengembangan yang tepat adalah kunci untuk pengembangan plugin yang efisien. Pengaturan yang siap akan memungkinkan pengembangan kode, pengujian, dan pengembangan plugin yang lancar.

Alat dan Keterampilan yang Dibutuhkan

Sebelum memulai, pastikan Anda telah menginstal alat-alat berikut:

Pengaturan Monorepo [1][2].

Karena

__CAPGO_KEEP_0__ plugins Capacitor plugins Membuat Salinan dan Mengkloning Repositori

1. Mulailah dengan mengkloning repositori __CAPGO_KEEP_0__ plugins di __CAPGO_KEEP_1__. Kemudian, kloning repositori yang telah dikloning Anda:
   Start by forking the Capacitor plugins repository on GitHub. Then, clone your forked repository:

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

2. Jalankan perintah berikut untuk memasang semua yang Anda butuhkan dan membangun plugin:
   __CAPGO_KEEP_1__

   npm run build

3. Set Up Pengendalian Versi
   Gunakan cabang fitur untuk perubahan Anda dan jaga fork Anda sinkron dengan repositori upstream.

Mengatur Platform Asli

Untuk pengembangan lintas platform, Anda akan perlu mengonfigurasi baik lingkungan iOS maupun Android.

Untuk iOS:

• Unduh Xcode dari Mac App Store.

• Pasang alat perintah garis bawah menggunakan:

  xcode-select --install

• Pasang CocoaPods dengan:

  sudo gem install cocoapods

• Buatlah akun pengembang Apple dan sertifikat yang diperlukan.

• Gunakan SwiftLint (opsional) untuk menjaga code kualitas.

Untuk Android:

• Pasang Android Studio bersama dengan SDK terbaru dan perangkat virtual.
• Pastikan Anda telah menginstal JDK.
• Konfigurasi Android SDK yang tepat dalam Android Studio.

Setelah platform-platform ini terkonfigurasi, Anda akan siap untuk mengikuti praktik coding yang telah ditetapkan dan melanjutkan ke pengembangan plugin.

Code Standards Guide

Sekarang bahwa lingkungan pengembangan Anda telah terkonfigurasi, ikuti pedoman ini untuk membangun plugin yang mudah dipelihara dan digunakan.

Style Guide Compliance

__CAPGO_KEEP_0__ plugin ecosystem Capacitor plugin ecosystem ESLint Prettier, , dan SwiftLint. Berikut adalah ringkasan singkat tentang format yang diperlukan:__CAPGO_KEEP_0__

Plugin harus menggunakan TypeScript untuk keamanan jenis yang lebih baik dan fitur-fitur ES6+ seperti async/await. Selain itu, ikuti konvensi coding yang spesifik untuk platform Swift (iOS) dan Kotlin (Android).

Pengelolaan Error dan Tipe

Pengelolaan error yang konsisten sangat penting untuk kinerja lintas platform. Berikut adalah contoh:

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

Untuk keamanan tipe:

• Pakai interface yang fokus untuk kasus penggunaan tertentu.
• Pakai tipe union untuk variasi platform tertentu.

Dokumentasi Code

Dokumentasi yang baik adalah kunci untuk membuat plugin Anda dapat diakses dan mudah digunakan. Ikuti praktek-praktek ini:

1. Dokumentasi API: Tuliskan komentar JSDoc yang berfungsi dengan @capacitor/docgen. Contohnya:

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

2. Struktur README: Masukkan informasi penting seperti langkah instalasi, instruksi konfigurasi, persyaratan platform tertentu, contoh penggunaan, dan referensi API yang rinci.

Dokumentasi yang baik memastikan bahwa plugin Anda mudah diadopsi dan berkontribusi pada komunitas Capacitor yang lebih luas.

sbb-itb-f9944d2

Petunjuk Uji Plugin

Uji Capacitor plugin melibatkan fokus pada beberapa area kritis untuk memastikan fungsi yang halus dan keandalan.

Uji Jembatan Asli

Uji jembatan asli memastikan komunikasi yang tepat antara JavaScript dan code asli. Untuk memulai, atur lingkungan uji Anda dengan kerangka kerja yang disesuaikan untuk setiap platform.

Contoh berikut adalah Jest unit test untuk sisi 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);
  });
});

Untuk menguji di sisi asli, gunakan XCTest untuk iOS dan JUnit untuk Android. Contoh di bawah ini adalah untuk Android:

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

Setelah Anda telah memastikan fungsi jembatan asli utama berfungsi seperti yang diharapkan, lanjutkan ke pengujian alur kerja pengguna yang lengkap.

Pengujian Plugin Lengkap

To pastikan plugin Anda berfungsi dengan baik di berbagai skenario, tes berbagai kategori:

Untuk plugin dengan fitur yang kompleks, simulasikan skenario pengguna nyata. Misalnya, jika Anda sedang menguji plugin DeviceInfo, periksa untuk:

• Upload sukses di bawah kondisi jaringan yang berbeda
• Laporan kemajuan yang akurat
• Konsumsi memori selama transfer file besar

Pengujian OTA dengan Capgo

Alat-alat terbuka sumber Capgo membuatnya mudah untuk menginstal dan menguji perbarui dengan cepat. Berikut cara menggunakan:

1. Konfigurasi saluran perbarui seperti dev, staging, dan produksi.
2. Mengautomasi penginstalan dengan alat-alat CI/CD.
3. Mengirimkan perbarui secara instan.
4. Mengawasi kinerja dan masalah melalui Capgo dashboard.

Untuk peluncuran berperingkat, Capgo memungkinkan Anda untuk membatasi pembaruan ke sejumlah kecil pengguna. Misalnya, Anda dapat meluncurkan versi baru ke 25% pengguna setiap 24 jam:

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

Pendekatan berperingkat ini membantu mengidentifikasi masalah-masalah sejak awal dengan memanfaatkan umpan balik komunitas sebelum peluncuran penuh.

Proses Pull Request

Setelah Anda telah melakukan tes yang teliti terhadap perubahan, ikuti langkah-langkah berikut untuk mengirimkan pull request Anda:

Daftar Periksa Pengiriman PR

Sebelum mengirimkan, pastikan Anda telah menutup area-area kunci berikut:

Pedoman Komunitas

Saat berkolaborasi, ikuti praktik terbaik ini:

• Tanggapi umpan balik reviewer dengan cepat.
• Tetapkan diskusi fokus pada detail teknis.
• Gunakan fitur saran GitHub untuk mengusulkan code perubahan.
• Kirimkan pull request kecil yang fokus, yang menangani satu fitur atau masalah pada satu waktu.

Untuk perubahan yang lebih besar, ide yang baik adalah membuat issue terlebih dahulu dan diskusikan pendekatan Anda. Tim Capacitor bergantung pada GitHub Actions untuk periksa otomatis, dan semua periksaan harus berhasil sebelum pull request Anda dapat direview.

Buku Panduan Integrasi Capgo

Jika plugin Anda melibatkan pembaruan langsung, pastikan bekerja dengan lancar dengan Capgo sebelum mengirimkan:

1. Kontrol Versi
   Pakai versi semantik yang jelas untuk plugin Anda, dan catat semua perubahan dalam log perubahan. Sistem Capgo membantu mengikuti adopsi versi di perangkat pengguna.

2. Pengintegrasian CI/CD
   Integrasikan Capgo ke dalam pipeline CI/CD Anda untuk otomatisasi pengiriman update.

3. Pengawasan Pembaruan
   Monitor tingkat kesuksesan pengiriman dan pastikan konsisten dengan pedoman aplikasi toko.

Ringkasan

Untuk membuat kontribusi yang bermakna dengan plugin Anda, penting untuk mengikuti proses yang telah ditetapkan dan memenuhi standar komunitas. Ini termasuk menaati pedoman pengkodean Capacitor dan melakukan pengujian yang teliti.

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.

Daftar periksa PR menyoroti kebutuhan untuk pengiriman kualitas tinggi. Jika plugin Anda mendukung pembaruan langsung, mengintegrasikan dengan __CAPGO_KEEP_0__ (seperti yang disebutkan sebelumnya) dapat membantu Anda merilis pembaruan dengan cepat tanpa menunggu persetujuan aplikasi toko. keeping up with Capacitor updates mengikuti pembaruan __CAPGO_KEEP_0__

Perhatikan umpan balik pengguna dan lakukan pembaruan jika perlu. Upaya ini yang berkelanjutan membantu menjaga kualitas overall ekosistem dan menjaga plugin Anda berharga bagi pengembang.

Teruskan dari Panduan Kontribusi Plugin Capacitor

Jika Anda menggunakan Panduan Kontribusi Plugin Capacitor untuk merencanakan kerja plugin native, hubungkannya dengan Panduan Direktori Plugin Capgo untuk alur kerja produk di Panduan Direktori Plugin Capgo, Capacitor Plugins by Capgo for the implementation detail in Capacitor Plugins by Capgo, Mengambah atau Mengupdate Plugin untuk detail implementasi di Mengambah atau Mengupdate Plugin, Alternatif Plugin Enterprise Ionic untuk alur kerja produk di Ionic Enterprise Plugin Alternatives, dan Capgo Pembangunan Natively untuk alur kerja produk di Capgo Pembangunan Natively.