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 diperlukan.
• Ikuti Code Standar: Gunakan TypeScript, Swift, dan Kotlin dengan konvensi penamaan yang konsisten dan pengelolaan kesalahan.
• Tes Secara Teliti: Tuliskan unit tes untuk JavaScript, iOS, dan Android untuk memastikan keandalan.
• Dokumentasikan Jelas: Gunakan JSDoc dan file README untuk memudahkan adopsi.
• Kirimkan Permintaan Pull: Pastikan kualitas code, pengujian, dan dokumentasi tinggi sebelum berkontribusi.

Guida Lengkap untuk Sumber Terbuka - Bagaimana Berkontribusi

Pengaturan Lingkungan Pengembangan

Membuat lingkungan pengembangan yang tepat adalah kunci untuk pengembangan plugin yang efisien. Pengaturan yang siap akan memungkinkan pengembangan yang lancar, pengujian, dan pengembangan plugin Anda.

Alat dan Keterampilan yang Dibutuhkan

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

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

Mengatur Struktur Monorepo

The Capacitor plugins Sistem ekosistem ini bergantung pada struktur monorepo. Pendekatan ini memastikan pekerjaan Anda sesuai dengan standar komunitas sejak awal.

1. Membuat Salinan dan Mengkloning Repositori
   Mulai dengan membuat salinan dan mengkloning repositori Capacitor plugins di GitHub.

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

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

   npm run build

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

Mengatur Platform Nativ

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

Untuk iOS:

• Unduh Xcode dari Mac App Store.

• Instal perangkat lunak baris perintah menggunakan:

  xcode-select --install

• Instal CocoaPods dengan:

  sudo gem install cocoapods

• Tetapkan akun pengembang Apple dan sertifikat yang diperlukan.

• Gunakan SwiftLint (opsional) untuk menjaga kualitas code.

Untuk Android:

• Instal 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 terkonfigurasi, Anda akan siap untuk mengikuti praktik coding yang telah ditetapkan dan memasuki pengembangan plugin.

Pedoman Standar Code

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

Pengawasan Kompatibilitas gaya

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

Plugins harus menggunakan TypeScript untuk keamanan tipe yang lebih baik dan fitur-fitur ES6+ seperti async/await Selain itu, ikuti konvensi coding 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 tipe:

• Gunakan interface yang difokuskan pada kasus penggunaan tertentu.
• Aplikasikan tipe-tipe union untuk variasi yang spesifik platform.

Code Dokumentasi

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

1. API Dokumentasi: Tulis komentar JSDoc yang kompatibel dengan @capacitor/docgen Contoh:

/**
 * @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.

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

sbb-itb-f9944d2

Panduan Uji Plugin

Uji Capacitor plugin melibatkan fokus pada beberapa area kritis untuk memastikan fungsi yang lancar dan keandalan.

Uji Jembatan Asli

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

Contoh berikut ini 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);
  });
});

Untuk uji pada sisi asli, gunakan XCTest untuk iOS dan JUnit untuk Android. Contoh berikut ini adalah untuk Android:

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

Setelah Anda yakin fungsi bridge inti berfungsi seperti yang diharapkan, lanjutkan ke pengujian alur kerja pengguna yang lengkap.

Lakukan Uji Coba Plugin

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

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

• Unik berbagai kondisi jaringan
• Laporan kemajuan yang akurat
• Penggunaan memori selama transfer file besar

Pengujian OTA dengan Capgo

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

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

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

Pendekatan berfasa ini membantu mengidentifikasi masalah-masalah sejak awal dengan memanfaatkan umpan balik komunitas sebelum rilis penuh.

Proses Pull Request

Setelah Anda telah melakukan pengujian 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

Ketika berkolaborasi, ikuti praktik terbaik ini:

• Beri respons cepat atas feedback reviewer.
• Tetapkan diskusi pada detail teknis.
• Gunakan fitur saran GitHub untuk mengusulkan code perubahan.
• Kirimkan pull request kecil, fokus pada satu fitur atau masalah per satu kali.

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 berhasil sebelum pull request Anda dapat direview.

Capgo Panduan Integrasi

Jika plugin Anda melibatkan pembaruan live, pastikan itu berjalan lancar dengan Capgo sebelum mengirimkan:

1. Kontrol Versi
   Pakai versi semantik yang jelas untuk plugin Anda, dan catat semua perubahan dalam log perubahan. Sistem Capgo membantu mengikuti adopsi versi di perangkat pengguna.

2. Pengintegrasian CI/CD
   Integrasikan Capgo ke dalam pipeline CI/CD Anda untuk otomatisasi pengiriman pembaruan.

3. Pemantauan Pembaruan
   Pantau tingkat kesuksesan pengiriman dan pastikan kompatibilitas dengan pedoman toko aplikasi.

Ringkasan

Untuk berkontribusi secara signifikan dengan plugin Anda, penting untuk mengikuti proses yang telah ditetapkan dan memenuhi standar komunitas. Ini termasuk menepati pedoman pengkodean Capacitor dan melakukan tes yang teliti.

Dalam daftar periksa PR, menonjolkan kebutuhan untuk pengiriman yang berkualitas. 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 diintegrasikan, tetap terlibat dengan mengikuti masalah dan merilis pembaruan versi. Interaksi yang konsisten dengan komunitas, pemeliharaan yang konsisten, dan Mengikuti pembaruan Capacitor akan memastikan plugin Anda tetap berguna dan relevan. Pastikan Anda memperhatikan umpan balik pengguna dan melakukan pembaruan jika perlu. Upaya ini berkelanjutan membantu menjaga kualitas overall ekosistem dan menjaga plugin Anda berharga bagi pengembang.

Teruskan dari __CAPGO_KEEP_0__ Panduan Kontribusi Plugin

Keep going from Capacitor Plugin Contribution Guide

__CAPGO_KEEP_0__ Panduan Kontribusi Plugin Capacitor Plugin Contribution Guide __CAPGO_KEEP_0__ Direktori Plugin untuk alur kerja produk di Capgo Direktori Plugin, Capgo Plugin oleh __CAPGO_KEEP_1__ untuk detail implementasi di Capacitor Plugin oleh Capgo, for the implementation detail in Capacitor Plugins by Capgo, Adding or Updating Plugins 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.