Petunjuk Kontribusi Plugin Capacitor

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

• Konfigurasi Lingkungan Anda: Alat seperti Node.js, Xcode, dan Android Studio adalah penting.
• Ikuti Code Standar: Gunakan TypeScript, Swift, dan Kotlin dengan konvensi penamaan dan penanganan kesalahan yang konsisten.
• Uji Coba Secara Teliti: Tuliskan 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 tinggi code, 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].

Mengatur Repositori Monorepo

Repositori Capacitor plugin ekosistem bergantung pada struktur repositori 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:

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

2. Instal Ketergantungan dan Bangun
   Jalankan perintah berikut untuk menginstal semua yang Anda butuhkan dan membangun plugin:

   npm run build

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

Mengatur Platform Asli

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

Untuk iOS:

• Unduh Xcode dari App Store Mac.

• Instal alat perintah menggunakan:

  xcode-select --install

• Instal CocoaPods dengan:

  sudo gem install cocoapods

• Siapkan 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 memiliki JDK yang terinstal.
• Konfigurasi SDK Android yang tepat dalam Android Studio.

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

Pedoman Standar Code

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

Pedoman gaya Kompatibilitas

Untuk Ekosistem plugin Capacitor 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/await. Selain 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 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 dan disesuaikan dengan 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. 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 rujukan API yang rinci.

Well-written documentation ensures that your plugin is easy to adopt and contributes to the broader Capacitor community.

Uji coba plugin __CAPGO_KEEP_0__ 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 Capacitor. Untuk memulai, atur lingkungan uji coba Anda dengan framework yang disesuaikan dengan setiap platform.

Contoh dari sebuah

Native bridge testing ensures proper communication between JavaScript and native code. To get started, set up your testing environment with frameworks tailored to each platform.

Ensuring bahwa dokumentasi yang baik membuat plugin Anda mudah diadopsi dan berkontribusi pada komunitas __CAPGO_KEEP_0__ yang lebih luas. Native Bridge Tests 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 melakukan pengujian pada 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 bridge inti berfungsi seperti yang diharapkan, lanjutkan ke pengujian alur kerja pengguna yang lengkap.

Pengujian Plugin Selesai

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

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

• Upload sukses di bawah kondisi jaringan yang berbeda
• Laporan progress yang akurat
• Penggunaan memori selama transfer file besar

Pengujian OTA dengan Capgo

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

1. Konfigurasi saluran pembaruan seperti dev, staging, dan produksi.
2. Automasi pengiriman dengan alat CI/CD.
3. Pengiriman update secara instan.
4. Pantau kinerja dan masalah melalui Capgo dashboard.

Untuk peluncuran berlangkah, Capgo memungkinkan Anda untuk membatasi update ke sejumlah 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"
  }
}

Langkah ini membantu mengidentifikasi masalah sejak 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 Pengiriman PR

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

Pedoman Komunitas

- Ketika berkolaborasi, ikuti praktek terbaik ini:

• Responsif terhadap umpan balik reviewer.
• Pertahankan 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, sebaiknya buatlah isu terlebih dahulu dan diskusikan pendekatan Anda. Tim Capacitor mengandalkan GitHub Actions untuk pemeriksaan otomatis, dan semua pemeriksaan harus lolos sebelum permintaan pull Anda dapat diperiksa.

Capgo Integration Guide

Jika plugin Anda melibatkan pembaruan hidup, pastikan 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 catatan 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 build asli. Peran: Label UI singkat atau item navigasi. Kunci pesan `native_build_feature_ci_cd` (Fitur Build Asli Ci Cd).
   Pasang __CAPGO_KEEP_0__ ke dalam pipeline CI/CD Anda untuk mengautomatisasi pengiriman pembaruan.

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

Daftar checklist PR menyoroti kebutuhan untuk pengiriman berkualitas tinggi. 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 diintegrasikan, 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 membuat pembaruan jika perlu. Upaya ini yang berkelanjutan membantu menjaga kualitas overall ekosistem dan menjaga plugin Anda berharga bagi developer.

Teruslah dari Panduan Kontribusi Plugin Capacitor

Jika Anda menggunakan Panduan Kontribusi Plugin Capacitor untuk merencanakan kerja plugin native, hubungkan dengan Panduan Direktori Plugin Capgo untuk alur kerja produk di Panduan Direktori Plugin Capgo Panduan Direktori Plugin Capacitor oleh Capgo untuk detail implementasi di Capacitor Plugins oleh Capgo Tambahkan atau Perbarui Plugins untuk detail implementasi di Tambahkan atau Perbarui Plugins Alternatif Plugin Enterprise Ionic untuk alur kerja produk di Alternatif Plugin Enterprise Ionic, dan Capgo Build Natively untuk alur kerja produk di Capgo Build Natively.