Capacitor Panduan Kontribusi Plugin

Capacitor plugins 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 Studio Android adalah penting.
• Patuhi Code Standar: Gunakan TypeScript, Swift, dan Kotlin dengan konvensi penamaan dan pengelolaan kesalahan yang konsisten.
• Uji Coba Secara Teliti: Tulis unit test untuk JavaScript, iOS, dan Android untuk memastikan keandalan.
• Dokumentasikan Jelas: Gunakan JSDoc dan file README untuk memudahkan adopsi.
• Kirimkan Permintaan Pull: Pastikan kualitas code yang tinggi, pengujian, dan dokumentasi sebelum berkontribusi.

Petunjuk Lengkap untuk Sumber Terbuka - Bagaimana Berkontribusi

Pengaturan Lingkungan Pengembangan

Pengaturan 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:

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].

Pengaturan Monorepo

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

1. Fork dan Clone Repositori
   Mulai dengan menggandakan repositori plugin Capacitor di GitHub. Kemudian, clone repositori yang telah digandakan Anda:

   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:

   npm run build

3. Set Up Pengendalian Versi
   Gunakan cabang fitur untuk perubahan Anda dan pastikan repositori Anda disinkronisasi dengan repositori upstream.

Mengatur Platform Asli

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

Untuk iOS:

• Unduh Xcode dari App Store Mac.

• Pasang alat perintah menggunakan:

  xcode-select --install

• Instal CocoaPods dengan:

  sudo gem install cocoapods

• Pasang akun pengembang Apple dan sertifikat yang diperlukan.

• Pakai 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 di dalam Android Studio.

Setelah platform-platform ini terpasang, Anda akan siap untuk mengikuti praktik coding yang sudah ada dan memulai pengembangan plugin.

Code Standards Guide

Sekarang bahwa lingkungan pengembangan Anda sudah terpasang, ikuti pedoman ini untuk membuat plugin yang mudah dipelihara dan digunakan.

Pedoman gaya yang sesuai

Katakan Ekosistem Capacitor plugin Menggunakan standar coding yang ketat dengan alat seperti ESLint, Prettier, dan SwiftLint. Berikut adalah gambaran singkat tentang format yang diperlukan:

Plugin harus menggunakan TypeScript untuk keamanan tipe yang lebih baik dan fitur-fitur ES6+ seperti async/awaitIkuti konvensi coding platform khusus untuk Swift (iOS) dan Kotlin (Android).

Pengelolaan Kesalahan dan Tipe

Pengelolaan kesalahan yang konsisten sangat penting untuk kompatibilitas 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-tipe union untuk variasi yang spesifik platform.

Code Dokumentasi

Dokumentasi yang baik sangat penting untuk membuat plugin Anda lebih mudah diakses dan digunakan. Ikuti praktek-praktek ini:

1. API Dokumentasi: 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: 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 keandalan.

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

For tes di sisi native, 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 memastikan fungsi jembatan inti berfungsi seperti yang diharapkan, lanjutkan ke tes alur kerja pengguna yang lengkap.

Tes Plugin Lengkap

Untuk memastikan 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 yang Sukses di Bawah Berbagai Kondisi Jaringan
• Laporan Progress yang Akurat
• Penggunaan Memori Selama Transfer File Besar

Pengujian OTA dengan Capgo

Capgo’s alat-alat sumber terbuka membuatnya mudah untuk menginstal dan menguji pembaruan dengan cepat. Berikut cara menggunakan alat ini:

1. Konfigurasi Saluran Pembaruan seperti dev, staging, dan produksi.
2. Mengautomasi pengiriman dengan menggunakan alat CI/CD.
3. Mengirimkan pembaruan secara instan.
4. Mengawasi kinerja dan masalah melalui dashboard Capgo.

Untuk peluncuran berlangkah, Capgo memungkinkan Anda untuk membatasi pembaruan hanya untuk sebagian 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"
  }
}

Ini pendekatan berlangkah membantu mengidentifikasi masalah-masalah awal dengan memanfaatkan umpan balik komunitas sebelum rilis penuh.

Proses Pull Request

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

Daftar Pemeriksaan PR

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

Pedoman Komunitas

Ketika berkolaborasi, ikuti praktek terbaik ini:

• Mengikuti Kembali Feedback Pemirsa
• Mengikuti Diskusi yang Fokus pada Detail Teknis
• Gunakan saran fitur 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, sebaiknya buatlah masalah terlebih dahulu dan diskusikan pendekatan Anda. Tim Capacitor bergantung pada GitHub Actions untuk melakukan pengecekan otomatis, dan semua pengecekan harus berhasil sebelum permintaan pull Anda dapat dinilai.

Capgo Panduan Integrasi

Jika plugin Anda melibatkan pembaruan hidup, pastikan bahwa plugin Anda berfungsi dengan lancar dengan Capgo sebelum mengirimkan:

1. Kontrol Versi
   Gunakan 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. Pemantauan Pembaruan
   Pantau tingkat kesuksesan pengiriman dan pastikan bahwa plugin Anda sesuai 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 mengikuti pedoman pengkodean Capacitor dan melakukan tes yang teliti terhadap pekerjaan Anda.

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 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 mengikuti pembaruan Capacitor akan memastikan plugin Anda tetap berguna dan relevan.

Penting untuk memperhatikan umpan balik pengguna dan melakukan pembaruan jika perlu. Upaya yang berkelanjutan ini membantu menjaga kualitas overall ekosistem dan menjaga plugin Anda berharga bagi developer.

Teruslah dari Capacitor Guide Kontribusi Plugin

Jika Anda menggunakan Capacitor Guide Kontribusi Plugin untuk merencanakan pekerjaan plugin native, hubungkan dengan Capgo Direktori Plugin untuk alur kerja produk di Capgo Direktori Plugin, Capacitor Plugin oleh Capgo untuk detail implementasi di Capacitor Plugin oleh Capgo Tambah atau Perbarui Paket untuk detail implementasi di Tambah atau Perbarui Paket Pengganti Plugin Enterprise Ionic untuk alur kerja produk di Pengganti Plugin Enterprise Ionic, dan Capgo Build Natively untuk alur kerja produk di Capgo Build Natively.