Menambahkan plugin

Dokumen ini membahas cara membuat plugin baru. Meskipun proses yang dijelaskan adalah 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 How to Build a Plugin talk (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. Blok ini dirancang agar dapat digunakan dalam berbagai aplikasi Blockly, stabil, dan mudah digunakan. File tersebut disimpan di blockly-samples. Kolom untuk menyetel kecepatan motor dapat digunakan dalam banyak project robotika dan merupakan kandidat yang baik untuk plugin pihak pertama.

Plugin pihak ketiga dikelola dan dipublikasikan secara independen. Fitur 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 lakukan monkeypatch pada Blockly.
  • Memiliki API yang jelas dan terdokumentasi.
  • Jangan panggil fungsi pribadi atau paket dari inti Blockly, kecuali jika diberikan pengecualian oleh tim Blockly.
    • Mengganti fungsi paket pada subclass yang Anda tentukan diizinkan.
    • Jika Anda menginginkan pengecualian, ajukan permintaan kepada kami dalam masalah di blockly-samples.
  • Memiliki pengujian.

Proses

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

Saran

Plugin dimulai sebagai saran. Anda dapat menyarankan plugin dengan membuat masalah baru menggunakan template Permintaan Fitur. Untuk mengetahui informasi selengkapnya, baca cara menulis permintaan fitur.

Selain informasi permintaan fitur dasar, saran plugin harus mencakup:

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

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

Diskusi

Selanjutnya, plugin memasuki fase diskusi. Tahap ini mencakup:

  • Klarifikasi fungsi yang diinginkan.
  • Klarifikasi API plugin.
  • Merencanakan penerapan.
  • Merencanakan pengujian.
  • Diskusi 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. Semakin kecil cakupan plugin, semakin cepat fase diskusi dapat dilakukan. Plugin yang lebih besar dapat menarik perhatian komunitas dan memunculkan pendapat yang kuat tentang Solusi yang Tepat. Jika hal ini terjadi pada masalah Anda, selamat. Anda telah menemukan sesuatu yang diminati orang.

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

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

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

Penerapan

Langkah-langkah penerapan meliputi:

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

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

Penerapan 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 dalam plugin di repositori ini, minta tim Blockly untuk membuat cabang fitur untuk Anda.

Plugin harus ditambahkan ke file gh-pages/index.md di cabang master blockly-samples. Plugin ini akan 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 ingin perubahan dipublikasikan lebih cepat, harap catat hal tersebut di pull request Anda.

Situs Plugin juga diperbarui setiap kali plugin dipublikasikan.

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