Panduan Kontribusi Plugin Capacitor

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

• Menyiapkan Lingkungan Anda: Alat seperti Node.js, Xcode, dan Android Studio sangat penting.
• Mengikuti Standar Kode: Gunakan TypeScript, Swift, dan Kotlin dengan konvensi penamaan dan penanganan kesalahan yang konsisten.
• Uji Secara Menyeluruh: Tulis unit test untuk JavaScript, iOS, dan Android untuk memastikan kehandalan.
• Dokumentasi yang Jelas: Gunakan JSDoc dan file README untuk adopsi yang mudah.
• Kirim Pull Request: Pastikan kode berkualitas tinggi, pengujian, dan dokumentasi sebelum berkontribusi.

Panduan Lengkap Open Source - Cara Berkontribusi

Penyiapan Lingkungan Pengembangan

Membuat lingkungan pengembangan yang tepat adalah kunci untuk pengembangan plugin yang efisien. Pengaturan yang dipersiapkan dengan baik memungkinkan pengkodean, pengujian, dan penerapan plugin Anda berjalan lancar.

Alat dan Keterampilan yang Anda Butuhkan

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

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

Menyiapkan Monorepo

Ekosistem plugin Capacitor mengandalkan struktur monorepo. Pendekatan ini memastikan pekerjaan Anda selaras dengan standar komunitas sejak awal.

1. Fork dan Clone Repository
   Mulailah dengan melakukan fork repository plugin Capacitor di GitHub. Kemudian, clone repository yang telah Anda fork:

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

2. Instal Dependensi dan Build
   Jalankan perintah berikut untuk menginstal semua yang Anda butuhkan dan build plugin:

   npm run build

3. Siapkan Version Control
   Gunakan branch fitur untuk perubahan Anda dan jaga agar fork Anda tetap sinkron dengan repository upstream.

Menyiapkan Platform Native

Untuk pengembangan lintas platform, Anda perlu mengkonfigurasi lingkungan iOS dan Android.

Untuk iOS:

• Unduh Xcode dari Mac App Store.

• Instal command-line tools menggunakan:

  xcode-select --install

• Instal CocoaPods dengan:

  sudo gem install cocoapods

• Siapkan akun Apple Developer dan sertifikat yang diperlukan.

• Gunakan SwiftLint (opsional) untuk menjaga kualitas kode.

Untuk Android:

• Instal Android Studio beserta SDK terbaru dan perangkat virtual.
• Pastikan Anda memiliki JDK terinstal.
• Konfigurasi Android SDK dengan benar di dalam Android Studio.

Setelah platform-platform ini disiapkan, Anda akan siap mengikuti praktik pengkodean yang telah ditetapkan dan mulai mengembangkan plugin.

Panduan Standar Kode

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

Kepatuhan Panduan Gaya

Ekosistem plugin Capacitor menerapkan standar pengkodean yang ketat menggunakan alat seperti ESLint, Prettier, dan SwiftLint. Berikut gambaran singkat tentang format yang diperlukan:

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

Manajemen Error dan Tipe

Penanganan error yang konsisten sangat penting untuk kompatibilitas lintas platform. Berikut contohnya:

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:

• Gunakan interface yang fokus disesuaikan dengan kasus penggunaan tertentu.
• Terapkan tipe union untuk variasi khusus platform.
• Implementasikan penjaga tipe untuk memvalidasi tipe saat runtime [1].

Dokumentasi Kode

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

1. Dokumentasi API: Tulis komentar JSDoc yang bekerja 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: Sertakan informasi penting seperti langkah-langkah instalasi, instruksi konfigurasi, persyaratan khusus platform, contoh penggunaan, dan referensi API yang detail.

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

Panduan Pengujian Plugin

Pengujian plugin Capacitor melibatkan fokus pada beberapa area penting untuk memastikan fungsionalitas dan kehandalan yang lancar.

Pengujian Native Bridge

Pengujian native bridge memastikan komunikasi yang tepat antara JavaScript dan kode native. Untuk memulai, siapkan lingkungan pengujian Anda dengan framework yang disesuaikan untuk setiap platform.

Berikut contoh unit test Jest 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 pengujian di sisi native, gunakan XCTest untuk iOS dan JUnit untuk Android. Berikut contoh untuk Android:

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

Setelah Anda memastikan fungsionalitas bridge inti bekerja sesuai harapan, lanjutkan ke pengujian alur kerja pengguna yang lengkap.

Pengujian Plugin Lengkap

Untuk memastikan plugin Anda berkinerja baik di berbagai skenario, uji berbagai kategori:

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

• Unggahan berhasil dalam berbagai kondisi jaringan
• Pelaporan kemajuan yang akurat
• Penggunaan memori selama transfer file besar

Pengujian OTA dengan Capgo

Alat open-source Capgo memudahkan untuk menerapkan dan menguji pembaruan dengan cepat. Berikut cara menggunakannya:

1. Siapkan saluran pembaruan seperti dev, staging, dan production.
2. Otomatisasi penerapan dengan alat CI/CD.
3. Push pembaruan secara instan.
4. Pantau kinerja dan masalah melalui dashboard Capgo.

Untuk peluncuran bertahap, Capgo memungkinkan Anda membatasi pembaruan ke persentase 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 bertahap ini membantu mengidentifikasi masalah lebih awal dengan memanfaatkan umpan balik komunitas sebelum rilis penuh.

Proses Pull Request

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

Daftar Periksa PR

Sebelum mengirim, pastikan Anda telah mencakup area-area kunci ini:

Panduan Komunitas

Saat berkolaborasi, ikuti praktik terbaik ini:

• Tanggapi dengan cepat umpan balik reviewer.
• Jaga diskusi tetap fokus pada detail teknis.
• Gunakan fitur saran GitHub untuk mengusulkan perubahan kode.
• Kirim pull request kecil dan terfokus yang menangani satu fitur atau masalah pada satu waktu.

Untuk perubahan yang lebih besar, sebaiknya buat issue terlebih dahulu dan diskusikan pendekatan Anda. Tim Capacitor mengandalkan GitHub Actions untuk pemeriksaan otomatis, dan semua pemeriksaan harus lulus sebelum pull request Anda dapat ditinjau.

Panduan Integrasi Capgo

Jika plugin Anda melibatkan pembaruan langsung, pastikan berfungsi dengan mulus dengan Capgo sebelum mengirim:

1. Kontrol Versi
   Gunakan versi semantik yang jelas untuk plugin Anda, dan dokumentasikan semua perubahan dalam changelog. Sistem Capgo membantu melacak adopsi versi di seluruh perangkat pengguna.

2. Integrasi CI/CD
   Integrasikan Capgo ke dalam pipeline CI/CD Anda untuk mengotomatisasi penerapan pembaruan.

3. Pemantauan Pembaruan
   Pantau tingkat keberhasilan penerapan dan pastikan kepatuhan dengan pedoman app store.

Ringkasan

Untuk memberikan kontribusi yang berarti dengan plugin Anda, penting untuk mengikuti proses yang telah ditetapkan dan memenuhi standar komunitas. Ini termasuk mengikuti pedoman pengkodean Capacitor dan menguji pekerjaan Anda secara menyeluruh.

Daftar periksa PR menekankan kebutuhan akan pengajuan berkualitas tinggi. Jika plugin Anda mendukung pembaruan langsung, integrasi dengan Capgo (seperti disebutkan sebelumnya) dapat membantu Anda merilis pembaruan dengan cepat tanpa menunggu persetujuan app store.

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

Perhatikan umpan balik pengguna dan lakukan pembaruan sesuai kebutuhan. Upaya berkelanjutan ini membantu mempertahankan kualitas keseluruhan ekosistem dan menjaga plugin Anda tetap berharga bagi pengembang.