Panduan Kontribusi Plugin Capacitor

Capacitor plugin menghubungkan teknologi web dengan fitur perangkat native, memungkinkan Pengembangan Aplikasi Berbasis Multi-PlatformGuide ini membantu Anda:

• Menyiapkan Lingkungan Anda: Alat seperti Node.js, Xcode, dan Android Studio adalah sangat penting.
• Ikuti Code Standar: Gunakan TypeScript, Swift, dan Kotlin dengan konvensi penamaan dan pengelolaan kesalahan yang konsisten.
• 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 tinggi code, pengujian, dan dokumentasi sebelum berkontribusi.

Guida Lengkap untuk Sumber Terbuka - Bagaimana Berkontribusi

Pengaturan Lingkungan Pengembangan

Mengatur 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 bergantung pada struktur monorepo. Pendekatan ini memastikan pekerjaan Anda sesuai dengan standar komunitas sejak awal.

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

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

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

   npm run build

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

Mengatur Platform Nativ

Untuk pengembangan lintas platform, Anda perlu mengonfigurasi baik lingkungan iOS maupun 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

• Atur akun pengembang Apple dan sertifikat yang diperlukan.

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

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

Code Standards Guide

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

Pedoman gaya yang patuh

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

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

Manajemen Error dan Tipe

Pengelolaan error 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 jenis data:

• Gunakan interface yang fokus untuk kasus penggunaan tertentu.
• Aplikasikan 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 kompatibel dengan @capacitor/docgenContoh:

/**
 * @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 rujukan API yang rinci.

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

Uji Jembatan Asli

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

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

Pengujian pada sisi asli menggunakan 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 utama berfungsi seperti yang diharapkan, lanjutkan ke pengujian alur kerja pengguna yang lengkap.

Uji Coba Plugin Lengkap

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

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

• Uploads yang Sukses di Bawah Berbagai Kondisi Jaringan
• Laporan Progress yang Akurat
• Penggunaan Memori Selama Transfer File Besar

Pengujian OTA dengan Capgo

Capgo memiliki alat-alat sumber terbuka yang memudahkan untuk menginstal dan menguji update dengan cepat. Berikut cara menggunakan alat-alat tersebut:

1. Konfigurasi saluran update seperti dev, staging, dan produksi.
2. Menggunakan alat-alat CI/CD untuk mengautomasi proses penginstalan.
3. Mengirimkan update secara instan.
4. Monitor kinerja dan masalah melalui Capgo dashboard.

Untuk peluncuran berlangkah, 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"
  }
}

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

Proses Pull Request

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

Daftar Pemeriksaan PR

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

Pedoman Komunitas

Mengikuti praktek terbaik saat berkolaborasi:

• Menggunakan umpan balik reviewer dengan cepat.
• Mengusahakan diskusi tetap fokus pada detail teknis.
• Menggunakan fitur saran GitHub untuk mengusulkan code perubahan.
• Mengirimkan pull request kecil yang fokus pada satu fitur atau masalah per satu kali.

Untuk perubahan yang lebih besar, sebaiknya buatlah isu terlebih dahulu dan diskusikan pendekatan Anda. Tim Capacitor mengandalkan GitHub Actions untuk melakukan pengecekan otomatis, dan semua pengecekan harus berhasil sebelum pull request Anda dapat direview.

Capgo Panduan Integrasi

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

1. Kontrol Versi
   Use clear semantic versioning for your plugin, and document all changes in the changelog. Capgo’s system helps track version adoption across user devices.

2. Pakai versi semantik yang jelas untuk plugin Anda, dan catat semua perubahan dalam log perubahan. Sistem __CAPGO_KEEP_0__ membantu mengikuti adopsi versi di perangkat pengguna.
   Integrate Capgo into your CI/CD pipeline to automate update deployments.

3. context: Halaman/area: Halaman produk Capgo Builder / produk cloud build asli. Peran: Label UI singkat atau item navigasi. Kunci pesan `native_build_feature_ci_cd` (Fitur Pembangunan Asli Ci Cd).
   Pakai __CAPGO_KEEP_0__ dalam pipeline CI/CD Anda untuk mempercepat proses pengiriman pembaruan.

Pemantauan Pembaruan

To make a meaningful contribution with your plugin, it’s important to follow the established process and meet community standards. This includes sticking to Capacitor’s coding guidelines and thoroughly testing your work.

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.

Untuk berkontribusi dengan bermakna dengan plugin Anda, penting untuk mengikuti proses yang telah ditetapkan dan memenuhi standar komunitas. Ini termasuk mengikuti pedoman pengkodean __CAPGO_KEEP_0__ dan melakukan pengujian yang teliti terhadap pekerjaan Anda. terus-menerus mengikuti Capacitor pembaruan 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 pengembang.

Teruskan dari Capacitor Panduan Kontribusi Plugin

Jika Anda menggunakan Capacitor Panduan Kontribusi Plugin untuk merencanakan kerja plugin native, hubungkan dengan Capgo Daftar Plugin untuk alur kerja produk di Capgo Daftar Plugin, Capacitor Plugin oleh Capgo untuk detail implementasi di Capacitor Plugin oleh Capgo, Mengambah 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 Pembangunan Natively, Untuk alur kerja produk di Capgo Pembangunan Natively.