Capacitor Panduan Kontribusi Plugin

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

• Sesuaikan Lingkungan Anda: Alat seperti Node.js, Xcode, dan Android Studio adalah penting.
• Ikuti Code Standar: Gunakan TypeScript, Swift, dan Kotlin dengan konvensi penamaan yang konsisten dan penanganan kesalahan.
• Uji Coba Secara Teliti: Tulis unit test untuk JavaScript, iOS, dan Android untuk memastikan keandalan.
• Dokumentasikan Jelas: Gunakan JSDoc dan file README untuk adopsi yang mudah.
• Kirimkan Permintaan Pull: Pastikan kualitas code yang tinggi, pengujian, dan dokumentasi sebelum berkontribusi.

Guida Lengkap Terbuka Sumber - Bagaimana Berkontribusi

Konfigurasi Lingkungan Pengembangan

Membuat lingkungan pengembangan yang tepat adalah kunci untuk pengembangan plugin yang efisien. Konfigurasi 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:

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 Repositori Monorepo

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

1. Buat Salinan dan Clone Repository
   Mulai dengan membuat salinan Capacitor plugin-plugin repository di GitHub. Kemudian, clone salinan yang telah dibuat:

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

2. Pasang Dependensi dan Bangun
   Jalankan perintah berikut untuk memasang semua yang Anda butuhkan dan membangun plugin-plugin:

   npm run build

3. Tetapkan Kontrol Versi
   Gunakan cabang fitur untuk perubahan Anda dan pastikan salinan Anda sinkron dengan repository upstream.

Mengatur Platform Nativ

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

Untuk iOS:

• Unduh Xcode dari App Store Mac.

• Instal perangkat lunak baris perintah menggunakan:

  xcode-select --install

• Instal CocoaPods dengan:

  sudo gem install cocoapods

• Set up akun pengembang Apple dan sertifikat yang diperlukan.

• Gunakan SwiftLint (opsional) untuk menjaga code kualitas.

Untuk Android:

• Instal Android Studio bersama dengan SDK terbaru dan perangkat virtual.
• Pastikan Anda memiliki JDK terinstal.
• Konfigurasi SDK Android yang tepat dalam Android Studio.

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

Code Standards Guide

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

Pedoman gaya Kompatibilitas

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

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

Pengelolaan Kesalahan dan Tipe

Pengelolaan kesalahan yang konsisten sangat penting untuk kompatibilitas 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 difokuskan pada kasus penggunaan tertentu.
• Gunakan tipe-tipe union untuk variasi yang spesifik platform.

Code Dokumentasi

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. Misalnya:

/**
 * @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 Pengujian Plugin

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

Pengujian Jembatan Asli

Pengujian jembatan asli memastikan komunikasi yang tepat antara JavaScript dan code. Untuk memulai, atur lingkungan pengujian Anda dengan framework yang disesuaikan dengan setiap platform.

Contoh berikut adalah contoh pengujian unit untuk sisi JavaScript: Pengujian untuk sisi native dapat menggunakan XCTest untuk iOS dan JUnit untuk Android. Contoh berikut adalah untuk Android: Setelah Anda memastikan fungsi bridge inti berfungsi seperti yang diharapkan, lanjutkan ke pengujian alur kerja pengguna yang lengkap.

// 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);
  });
});

Pengujian Plugin Lengkap

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

Untuk memastikan plugin Anda berfungsi dengan baik dalam skenario yang berbeda-beda, uji berbagai kategori:

Kategori Pengujian

Daerah Fokus Utama

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

• Unjuk kerja upload yang sukses di bawah kondisi jaringan yang berbeda
• Laporan kemajuan yang akurat
• Penggunaan memori selama transfer file besar

Uji Perbarui OTA dengan Capgo

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

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

Untuk peluncuran berfase, Capgo memungkinkan Anda untuk membatasi pembaruan hanya kepada sekelompok kecil pengguna. Misalnya, Anda dapat mengeluarkan 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 berfase ini membantu mengidentifikasi masalah-masalah sejak awal dengan memanfaatkan umpan balik komunitas sebelum peluncuran penuh.

Proses Pull Request

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

Daftar Pemeriksaan Pengiriman PR

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

Pedoman Masyarakat

Ketika berkolaborasi, ikuti praktik terbaik ini:

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

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

Capgo Guide Integrasi

Jika plugin Anda melibatkan pembaruan hidup, pastikan bekerja dengan 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. Pengawasan Pembaruan
   Monitor keberhasilan pengiriman dan pastikan konsisten dengan pedoman toko aplikasi.

Summary

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

Daftar PR menyoroti kebutuhan pengiriman yang berkualitas. Jika plugin Anda mendukung pembaruan langsung, mengintegrasikan dengan Capgo (seperti yang disebutkan sebelumnya) dapat membantu Anda merilis pembaruan dengan cepat tanpa harus menunggu persetujuan toko aplikasi.

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

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

Teruslah dari Capacitor Plugin Contribution Guide

Jika Anda menggunakan Capacitor Plugin Contribution Guide untuk merencanakan kerja plugin native, hubungkan dengan Capgo Plugin Directory untuk alur kerja produk di Direktori Plugin Capgo Capacitor Plugin oleh Capgo untuk detail implementasi di Capacitor Plugin oleh Capgo Menambahkan atau Mengupdate Plugin untuk detail implementasi di Menambahkan atau Mengupdate Plugin Alternatif Plugin Enterprise Ionic untuk alur kerja produk di Alternatif Plugin Enterprise Ionic, dan Capgo Build Nativ untuk alur kerja produk di Capgo Build Nativ