Capacitor Panduan Kontribusi Plugin

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

• Tetapkan Lingkungan Anda: Alat seperti Node.js, Xcode, dan Android Studio diperlukan.
• Ikuti Code Standar: Gunakan TypeScript, Bahasa Swift, dan Bahasa Kotlin dengan konvensi penamaan yang konsisten dan penanganan kesalahan.
• Tes Secara Teliti: Tuliskan unit tes untuk JavaScript, iOS, dan Android untuk memastikan keandalan.
• Dokumentasikan Jelas: Gunakan JSDoc dan file README untuk memudahkan penyerapan.
• 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 sangat penting untuk pengembangan plugin yang efisien. Pengaturan yang siap akan memungkinkan pengembangan yang lancar, pengujian, dan pengembangan plugin Anda.

Alat dan Keterampilan yang Dibutuhkan

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

Anda juga harus nyaman dengan TypeScript untuk pengembangan web dan salah satu Swift (untuk iOS) atau Java/Kotlin (untuk Android) untuk tugas pengembangan native [1][2].

Mengatur Struktur Monorepo

The Capacitor plugins Ecosistem ini bergantung pada struktur monorepo. Pendekatan ini memastikan pekerjaan Anda sesuai dengan standar komunitas sejak awal.

1. Membuat dan Mengkloning Repositori
   Mulai dengan membuat salinan Capacitor plugins repository di GitHub. Kemudian, kloning repositori yang telah disalin Anda:

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

2. Instalasi Dependensi dan Pembangunan
   Jalankan perintah berikut untuk menginstal semua yang Anda butuhkan dan membangun plugin:

   npm run build

3. Sesuaikan Pengendalian Versi
   Gunakan cabang fitur untuk perubahan Anda dan pastikan fork Anda sinkron dengan repositori upstream.

Mempersiapkan Platform Nativ

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

Untuk iOS:

• Unduh Xcode dari Mac App Store.

• Instal perangkat lunak baris perintah menggunakan:

  xcode-select --install

• Instal CocoaPods dengan:

  sudo gem install cocoapods

• Sesuaikan akun pengembang Apple dan sertifikat yang diperlukan.

• Gunakan SwiftLint (opsional) untuk menjaga code kualitas.

Untuk Android:

• Pasang Android Studio bersama dengan versi terbaru SDK dan perangkat virtual.
• Pastikan Anda telah menginstal JDK.
• Konfigurasi SDK Android dengan benar di dalam Android Studio.

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

Code Standards Guide

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

Kompatibilitas Pedoman gaya

The Capacitor plugin ecosystem mengenakan standar pengkodean yang ketat menggunakan alat seperti ESLint, Prettier, dan SwiftLint. Berikut adalah gambaran singkat tentang format yang diperlukan:

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

Pengelolaan Kesalahan dan Tipe

Pengelolaan kesalahan yang konsisten sangat penting untuk konsistensi lintas-platform. Berikut 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 jenis:

• Gunakan interface yang fokus untuk kasus penggunaan tertentu.
• Terapkan tipe union untuk variasi spesifik platform.

Code Dokumentasi

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

1. API Dokumentasi: Tulis komentar JSDoc yang kompatibel dengan @capacitor/docgenContoh: Tulis komentar JSDoc yang kompatibel dengan

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

2. Struktur README: Termasuk informasi penting seperti langkah instalasi, instruksi konfigurasi, persyaratan platform khusus, 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

Panduan Uji Plugin

Uji Capacitor plugin melibatkan fokus pada beberapa area kritis untuk memastikan fungsi yang lancar dan dapat diandalkan.

Uji Jembatan Asli

Uji jembatan asli memastikan komunikasi yang tepat antara JavaScript dan code. Untuk memulai, atur lingkungan uji Anda dengan kerangka kerja yang disesuaikan dengan 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 uji pada sisi asli, gunakan XCTest untuk iOS dan JUnit untuk Android. Contoh berikut adalah untuk Android:

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

Setelah Anda yakin fungsi bridge inti berfungsi seperti yang diharapkan, lanjutkan ke pengujian alur kerja pengguna yang lengkap.

Tes Plugin Lengkap

Untuk memastikan plugin Anda berfungsi dengan baik di berbagai skenario, lakukan tes kategori-kategori berikut:

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

• Unsur terunggul dalam kondisi jaringan yang berbeda
• Laporan kemajuan yang akurat
• Penggunaan memori selama transfer file besar

Pengujian OTA dengan Capgo

Capgo’s tools terbuka sumber membuatnya mudah untuk mengaktifkan dan menguji pembaruan dengan cepat. Berikut cara menggunakan:

1. Tetapkan saluran pembaruan seperti dev, staging, dan produksi.
2. Automasi pengaktifan dengan alat CI/CD.
3. Push pembaruan secara instan.
4. Monitor kinerja dan masalah melalui Capgo dashboard.

Untuk peluncuran berlangsung, 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 berlangsung ini membantu mengidentifikasi masalah-masalah awal dengan memanfaatkan umpan balik komunitas sebelum peluncuran penuh.

Proses Pull Request

Setelah Anda telah menguji perubahan secara menyeluruh, ikuti langkah-langkah ini untuk mengirimkan pull request Anda:

Daftar Pemeriksaan Pengiriman PR

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

Pedoman Komunitas

Ketika berkolaborasi, ikuti praktik terbaik ini:

• Tanggapi dengan cepat feedback reviewer.
• Tetapkan diskusi pada detail teknis.
• Gunakan fitur saran GitHub untuk mengusulkan code perubahan.
• Kirimkan pull request kecil yang fokus pada satu fitur atau masalah per satu kali.

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

Capgo Panduan Integrasi

Jika plugin Anda melibatkan pembaruan live, pastikan itu berjalan lancar dengan Capgo sebelum mengirimkan:

1. Pengendalian Versi
   Gunakan pengendalian versi semantik yang jelas untuk plugin Anda, dan dokumentasikan semua perubahan dalam catatan perubahan. Sistem Capgo membantu mengikuti adopsi versi di perangkat pengguna.

2. Integrasi CI/CD
   Integrasikan Capgo ke dalam pipeline CI/CD Anda untuk otomatisasi pengiriman pembaruan.

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

Ringkasan

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

Daftar Periksa PR menyoroti kebutuhan untuk pengiriman kualitas tinggi. Jika plugin Anda mendukung pembaruan live, mengintegrasikan dengan Capgo (seperti yang disebutkan sebelumnya) dapat membantu Anda merilis pembaruan dengan cepat tanpa menunggu persetujuan toko aplikasi.

Setelah PR Anda disatukan, tetap terlibat dengan mengikuti masalah dan merilis pembaruan versi. Interaksi yang teratur dengan komunitas, pemeliharaan yang konsisten, dan Mengikuti pembaruan Capacitor akan memastikan plugin Anda tetap berguna dan relevan.

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