Bu belgede, yeni bir eklentinin nasıl oluşturulacağı açıklanmaktadır. Bu makalede açıklanan işlem birinci taraf eklentileri oluşturmaya yönelik olsa da üçüncü taraf eklentileri oluşturmak için kılavuz olarak kullanabilirsiniz.
Eklentilere genel bakış için Eklentiler başlıklı makaleyi inceleyin.
Eklenti oluşturmaya hızlı bir giriş için How to Build a Plugin talk (2021) (Eklenti Oluşturma Konuşması) başlıklı makalemize göz atın.
Birinci taraf ve üçüncü taraf
Bir eklentinin hedef kullanıcısı, eklentiyi npm üzerinden bulan ve kullanan bir geliştiricidir.
Birinci taraf eklentileri Blockly ekibi tarafından desteklenir ve npm'de @blockly kapsamı altında yayınlanır. Geniş bir Blockly uygulaması yelpazesinde kullanılacak şekilde tasarlanmış olup kararlı ve kullanımı kolaydır. Bunlar blockly-samples içinde saklanır. Motor hızını ayarlama alanı birçok robotik projesinde kullanılabilir ve birinci taraf eklentisi için iyi bir adaydır.
Üçüncü taraf eklentileri bağımsız olarak korunur ve yayınlanır. Bunlar daha karmaşık, daha deneysel veya daha dar bir Blockly uygulamaları aralığını hedefliyor olabilir. Veritabanı şemanızda tanımlanan belirli bir nesnenin düzenlenmesi için kullanılan alan, üçüncü taraf eklentisi olarak daha uygundur.
Birinci taraf ölçütleri
Birinci taraf eklentileri şu koşulları karşılamalıdır:
- Blockly ekibi tarafından muafiyet verilmediği sürece tüm büyük platformlarda çalışır.
- Chrome, Firefox, Safari, Edge
- İlk yıl boyunca hataları düzeltmeye istekli bir yazarınız olmalıdır.
- Blockly'ye yama uygulamayın.
- Net bir şekilde tanımlanmış ve belgelenmiş bir API'ye sahip olun.
- Blockly ekibi tarafından muafiyet verilmediği sürece Blockly çekirdeğinden özel veya paket işlevlerini çağırmayın.
- Tanımladığınız bir alt sınıfta paket işlevlerini geçersiz kılmaya izin verilir.
- Muafiyet istiyorsanız blockly-samples'daki bir sorunda bize bildirin.
- Testler
Süreç
Eklentiler dört aşamadan geçer: öneri, tartışma, uygulama ve yayınlama.
Öneri
Eklentiler öneri olarak başlar. Özellik İsteği şablonunu kullanarak yeni bir sorun oluşturarak eklenti önerebilirsiniz. Daha fazla bilgi için özellik isteği yazma hakkında bilgi edinin.
Temel özellik isteği bilgilerine ek olarak, eklenti önerisi şunları içermelidir:
- Eklentinin kullanıma sunacağı API.
- Eklentiyi desteklemek için temel Blockly'ye eklenmesi veya değiştirilmesi gereken API'ler.
- Eklenti kullanıcı arayüzü özellikleri içeriyorsa ekran görüntüleri, GIF'ler veya taslaklar.
- Neden üçüncü taraf eklentisi yerine birinci taraf eklentisi olması gerektiğine dair açıklama.
Blockly ekibi, önerileri alır almaz inceler ve sorunu kapatır veya iyi bir birinci taraf eklentisi olacağını kabul eder.
Tartışma
Ardından, eklenti tartışma aşamasına geçer. Bu aşamada şunlar yer alır:
- İstenen işlevin netleştirilmesi.
- Eklentinin API'siyle ilgili açıklama.
- Uygulama için planlama.
- Testler için planlama
- Temel Blockly'deki API değişikliklerinin tartışılması.
- Büyük eklentileri uygulama adımlarına bölme
- Adlandırma kurallarımıza göre eklenti adlandırması.
- Tüm birinci taraf ölçütlerinin karşılanacağını onaylayın.
Bu tartışma genellikle GitHub sorunu üzerinde yapılır. Eklentinin kapsamı ne kadar küçükse tartışma aşaması o kadar hızlı olabilir. Daha büyük eklentiler, topluluğun dikkatini çekebilir ve Doğru Çözüm hakkında güçlü görüşler ortaya çıkabilir. Bu durum sorununuzda gerçekleşirse tebrikler! Kullanıcıların ilgisini çeken bir şey buldunuz.
Amaç, tartışma aşamasının sonunda tüm önemli tasarım kararlarının alınması ve uygulama adımlarının net bir şekilde listelenmesidir. Her ikisi de sorunun yorumlarında belgelenmelidir.
Tartışma sırasında, bir eklentinin üçüncü taraf eklentisi olması ve @blockly kapsamında yayınlanmaması gerektiğine karar verebiliriz. Bu durumda, nedenini açıklayıp sorunu kapatırız.
Tartışma tamamlandığında Blockly ekibi üyesi, tartışmanın uygulanmaya hazır olduğunu belirtir.
Uygulama
Uygulama adımları şunlardır:
- Eklentiyi ve dizinini bir şablondan oluşturmak için
npx @blockly/create-packagekomutunu çalıştırma. Daha fazla bilgi... - Eklenti için temel mantığı uygulama.
- Gerekirse kullanıcı arayüzü uygulama
- Mocha kullanarak eklentiyi test etme.
- Eklentiyi,
READMEdahil olmak üzere belgeleme
Uygulanması için onaylanmış bir eklenti önerisi varsa ve bu eklenti üzerinde çalışmak istiyorsanız konu hakkında yorum yapın ve katkı için hâlâ açık olup olmadığını sorun.
Uygulama, birden fazla katkıda bulunan tarafından paralel olarak yapılabilir. Eklentiyi kendi çatallamanızda ortak çalışarak veya bu depoya karşı çekme istekleri aracılığıyla uygulayabilirsiniz. Bu depodaki bir eklenti üzerinde iş birliği yapmak istiyorsanız Blockly ekibinden sizin için bir özellik dalı oluşturmasını isteyin.
Eklentiler, blockly-samples'ın master dalındaki gh-pages/index.md dosyasına eklenmelidir. Bu, eklentilerin Eklentiler sitemizde görünmesine neden olur. Birinci taraf eklentileri, test sayfalarına yönlendirmelidir. Bu sayfaya üçüncü taraf eklentileri de eklenebilir ve bu eklentiler, sahiplerinin seçtiği bir bağlantıya (ör. barındırılan bir demo veya npm sayfası) yönlendirebilir.
Yayıncılık
Son olarak yayınlama. Blockly ekibi, tüm eklentilerde sürüm oluşturma ve yayınlama işlemlerini yönetmek için Lerna'yı kullanır.
Her perşembe günü, son yayınlanmalarından bu yana değişen tüm eklentiler yayınlanır. Bir değişikliğin daha erken yayınlanması gerekiyorsa lütfen çekme isteğinizde belirtin.
Eklentiler sitesi de eklentiler yayınlandığında güncellenir.
Yayınlanmaya hazır olmayan eklentiler, package.json içinde private olarak işaretlenmelidir. Bu durum, bir eklenti çekirdek Blockly'de henüz yayınlanmamış bir değişikliğe bağlıysa meydana gelebilir. Core Blockly, her çeyreğin son haftasında (üç ayda bir) yayınlanır.