Menambahkan plugin

Dokumen ini membahas cara membuat plugin baru. Meskipun proses yang dijelaskannya ditujukan untuk membuat plugin pihak pertama, Anda dapat menggunakannya sebagai panduan untuk membuat plugin pihak ketiga.

Untuk mengetahui ringkasan plugin, lihat Plugin.

Untuk pengantar singkat tentang cara membuat plugin, lihat presentasi Cara Membuat Plugin (2021).

Pihak pertama vs. pihak ketiga

Pengguna target untuk plugin adalah developer yang menemukan dan menggunakan plugin melalui npm.

Plugin pihak pertama didukung oleh tim Blockly dan dipublikasikan dalam cakupan @blockly di npm. Alat ini dirancang agar dapat digunakan di berbagai aplikasi Blockly serta stabil dan mudah digunakan. Contoh ini disimpan di blockly-samples. Kolom untuk menetapkan kecepatan motor dapat digunakan di banyak project robotika dan merupakan kandidat yang baik untuk plugin pihak pertama.

Plugin pihak ketiga dikelola dan dipublikasikan secara independen. Aplikasi ini mungkin lebih kompleks, lebih eksperimental, atau ditargetkan ke rentang aplikasi Blockly yang lebih sempit. Kolom untuk mengedit objek tertentu yang ditentukan oleh skema database Anda lebih baik sebagai plugin pihak ketiga.

Kriteria pihak pertama

Plugin pihak pertama harus memenuhi persyaratan berikut:

  • Berfungsi di semua platform utama, kecuali jika diberi pengecualian oleh tim Blockly.
    • Chrome, Firefox, Safari, Edge
  • Memiliki penulis yang bersedia menangani bug selama tahun pertama.
  • Jangan melakukan monkeypatch pada Blockly.
  • Memiliki API yang jelas dan terdokumentasi.
  • Jangan memanggil fungsi pribadi atau paket dari core Blockly, kecuali jika diberikan pengecualian oleh tim Blockly.
    • Mengganti fungsi paket pada subclass yang Anda tentukan diizinkan.
    • Jika Anda menginginkan pengecualian, ajukan pertanyaan kepada kami di masalah pada blockly-samples.
  • Memiliki pengujian.

Proses

Plugin melalui empat tahap: saran, diskusi, implementasi, dan publikasi.

Saran

Plugin dimulai sebagai saran. Anda dapat menyarankan plugin dengan membuat masalah baru menggunakan template Permintaan Fitur.

Baca cara menulis permintaan fitur

Selain informasi permintaan fitur dasar, saran plugin harus menyertakan:

  • API yang akan diekspos plugin.
  • API yang perlu ditambahkan atau diubah di Blockly inti untuk mendukung plugin.
  • Screenshot, GIF, atau mockup jika plugin menyertakan fitur UI.
  • Penjelasan mengapa plugin harus berupa plugin pihak pertama, bukan plugin pihak ketiga.

Tim Blockly meninjau saran yang masuk dan menutup masalah atau menyetujui bahwa saran tersebut akan menjadi plugin pihak pertama yang baik.

Diskusi

Selanjutnya, plugin akan memasuki fase diskusi. Tahap ini mencakup:

  • Klarifikasi fungsi yang diinginkan.
  • Klarifikasi API plugin.
  • Merencanakan implementasi.
  • Merencanakan pengujian.
  • Diskusi tentang perubahan API di Blockly inti.
  • Membagi plugin besar menjadi langkah-langkah penerapan.
  • Penamaan plugin, berdasarkan konvensi penamaan kami.
  • Mengonfirmasi bahwa semua kriteria pihak pertama akan terpenuhi.

Diskusi ini biasanya terjadi di masalah GitHub. Makin kecil cakupan plugin, makin cepat fase diskusinya. Plugin yang lebih besar dapat menarik perhatian komunitas dan pendapat yang kuat tentang Solusi yang Tepat. Jika hal ini terjadi pada masalah Anda, selamat. Anda telah menemukan sesuatu yang penting bagi orang-orang.

Tujuannya adalah pada akhir fase diskusi, semua keputusan desain utama telah dibuat dan ada daftar langkah penerapan yang jelas. Keduanya harus didokumentasikan dalam komentar pada masalah tersebut.

Selama diskusi, kami dapat memutuskan bahwa plugin harus berupa plugin pihak ketiga, dan tidak dipublikasikan dalam cakupan @blockly. Dalam hal ini, kami akan menjelaskan alasannya dan menutup masalah.

Setelah diskusi selesai, anggota tim Blockly akan mencatat bahwa diskusi tersebut siap diimplementasikan.

Penerapan

Langkah-langkah penerapan meliputi:

  • Menjalankan npx @blockly/create-package untuk menyiapkan plugin dan direktorinya dari template. Pelajari lebih lanjut...
  • Mengimplementasikan logika inti untuk plugin.
  • Menerapkan UI, jika diperlukan.
  • Menguji plugin, menggunakan Mocha.
  • Mendokumentasikan plugin, termasuk README.

Jika plugin yang disarankan telah disetujui untuk diimplementasikan dan Anda ingin mengerjakannya, berikan komentar pada masalah tersebut dan tanyakan apakah plugin masih terbuka untuk kontribusi.

Implementasi dapat dilakukan oleh beberapa kontributor secara paralel. Anda dapat menerapkan plugin secara kolaboratif di fork Anda sendiri, atau melalui permintaan pull terhadap repositori ini. Jika Anda ingin berkolaborasi pada plugin di repositori ini, minta tim Blockly untuk membuat cabang fitur bagi Anda.

Plugin harus ditambahkan ke file gh-pages/index.md di cabang master dari blockly-samples. Tindakan ini akan menyebabkannya muncul di situs Plugin kami. Plugin pihak pertama harus mengarah ke halaman pengujiannya. Plugin pihak ketiga juga dapat ditambahkan ke halaman ini, dan dapat mengarah ke link pilihan pemiliknya, seperti demo yang dihosting atau halaman npm.

Publikasi

Terakhir, publikasi. Tim Blockly menggunakan Lerna untuk mengelola pembuatan versi dan publikasi untuk semua plugin.

Setiap hari Kamis, plugin apa pun yang telah berubah sejak rilis terakhirnya akan dipublikasikan. Jika Anda memerlukan perubahan untuk dipublikasikan lebih cepat, harap catat di pull request Anda.

Situs Plugin juga diperbarui setiap kali plugin dipublikasikan.

Plugin yang belum siap dipublikasikan harus ditandai private di package.json. Hal ini dapat terjadi jika plugin mengandalkan perubahan yang belum dipublikasikan di Blockly inti. Core Blockly dipublikasikan pada minggu terakhir setiap kuartal (satu kali setiap tiga bulan).