Bu dokümanda, yeni bir eklentinin nasıl oluşturulacağı ele alınmaktadır. Bu makalede açıklanan süreç birinci taraf eklentileri oluşturmak için olsa da üçüncü taraf eklentileri oluşturmak için de bu süreci kılavuz olarak kullanabilirsiniz.
Eklentilere genel bakış için Eklentiler başlıklı makaleyi inceleyin.
Eklenti oluşturma hakkında kısa bir giriş için Eklenti Oluşturma (2021) başlıklı konuşmamıza göz atın.
Birinci taraf ve üçüncü taraf
Bir eklentinin hedef kullanıcısı, eklentiyi npm üzerinden bulup kullanan geliştiricidir.
Birinci taraf eklentileri Blockly ekibi tarafından desteklenir ve npm'de @blockly kapsamında yayınlanır. Bu bloklar, çeşitli Blockly uygulamalarında kullanılabilecek şekilde tasarlanmıştır. Ayrıca kararlı ve kullanımı kolaydır. Bunlar blockly-samples klasöründe depolanır. Motor hızını ayarlamak için bir alan, birçok robotik projesinde kullanılabilir ve birinci taraf eklentisi için iyi bir adaydır.
Üçüncü taraf eklentileri bağımsız olarak yönetilir ve yayınlanır. Bunlar daha karmaşık, daha deneysel veya daha dar bir Blockly uygulaması yelpazesini hedefliyor olabilir. Veritabanı şemanız tarafından tanımlanan belirli bir nesneyi düzenlemek için bir alan, üçüncü taraf eklentisi olarak daha iyidir.
Birinci taraf ölçütleri
Birinci taraf eklentileri aşağıdaki koşulları karşılamalıdır:
- Blockly ekibi tarafından muafiyet verilmediği sürece tüm önemli platformlarda çalışır.
- Chrome, Firefox, Safari, Edge
- İlk yıl boyunca hataları gidermeye hazır bir yazarınız olmalıdır.
- Blockly'de monkeypatch yapmayın.
- Net bir şekilde tanımlanmış ve belgelenmiş bir API'niz olmalıdır.
- Blockly ekibi tarafından muafiyet verilmedikçe Blockly çekirdeğinden özel veya paket işlevleri çağırmayın.
- Tanımladığınız alt sınıftaki paket işlevlerinin geçersiz kılınmasına izin verilir.
- Muafiyet istiyorsanız blockly-samples ile ilgili bir sorunda bize sorun.
- 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 şablonuyla yeni bir sorun oluşturarak eklenti önerebilirsiniz.
Özellik isteği yazma hakkında bilgi edinin.
Eklenti önerileri, temel özellik isteği bilgilerine ek olarak şunları içermelidir:
- Eklentinin kullanıma sunacağı API.
- Eklentiyi desteklemek için temel Blockly'de 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 geldikçe inceler ve sorunu kapatır ya da 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şlev hakkında açıklama.
- Eklentinin API'si hakkında açıklama.
- Uygulama için planlama yapma
- Testler için planlama yapma
- Temel Blockly'deki API değişiklikleri hakkında tartışma.
- Büyük eklentileri uygulama adımlarına ayırma.
- Adlandırma kurallarımıza göre eklenti adlandırma.
- Tüm birinci taraf ölçütlerinin karşılanacağını onaylama.
Bu tartışma genellikle GitHub sorununda gerçekleşir. Eklentinin kapsamı ne kadar küçükse tartışma aşaması o kadar hızlı olabilir. Büyük eklentiler, topluluğun dikkatini çekebilir ve doğru çözüm hakkında güçlü görüşler sunabilir. Sorununuzla ilgili olarak bu durum gerçekleşirse tebrikler. Kullanıcıların önemsediği bir konu 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 listesinin oluşturulmasıdır. Her ikisi de sorunla ilgili yorumlarda belirtilmelidir.
Görüşme sırasında, bir eklentinin üçüncü taraf eklentisi olması ve @blockly kapsamı altında yayınlanmaması gerektiğine karar verebiliriz. Bu durumda nedenini açıklayıp sorunu kapatırız.
Tartışma tamamlandığında bir Blockly ekibi üyesi, özelliğin uygulanmasına hazır olduğunu belirtir.
Uygulama
Uygulama adımları şunlardır:
- Eklentiyi ve dizini bir şablondan ayarlamak için
npx @blockly/create-packageçalıştırma. Daha fazla bilgi edinin... - Eklentinin temel mantığını uygulama.
- Gerekirse kullanıcı arayüzü uygulama
- Mocha'yı kullanarak eklentiyi test etme.
READMEdahil olmak üzere eklentiyi belgeleme.
Önerilen bir eklenti kullanıma sunulması için onaylandıysa ve üzerinde çalışmak istiyorsanız konuyla ilgili yorum yapın ve katkıda bulunmaya açık olup olmadığını sorun.
Uygulama, birden fazla katkıda bulunan tarafından paralel olarak yapılabilir. Bir eklentiyi kendi çatalınızda veya bu depoya yönelik çekme istekleri aracılığıyla ortaklaşa uygulayabilirsiniz. Bu depoda bir eklenti üzerinde ortak çalışmak istiyorsanız Blockly ekibinden sizin için bir özellik dalı oluşturmasını isteyin.
Eklentiler, blockly-samples'in master dalındaki gh-pages/index.md dosyasına eklenmelidir. Bu, eklentilerin Eklentiler sitemizde görünmesine neden olur. Birinci taraf eklentileri, test sayfalarını işaret etmelidir. Bu sayfaya üçüncü taraf eklentileri de eklenebilir ve bu eklentiler, sahibinin tercihine göre 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 eklentilerin sürümlerini ve yayınlanmasını yönetmek için Lerna'yı kullanır.
Son sürümden bu yana değişen tüm eklentiler her Perşembe yayınlanır. Bir değişikliğin daha erken yayınlanması gerekiyorsa lütfen bunu çekme isteğinizde belirtin.
Eklentiler sitesi de eklenti yayınlandığında güncellenir.
Yayınlamaya hazır olmayan eklentiler, package.json bölümünde private olarak işaretlenmelidir. Bu durum, bir eklenti temel Blockly'de henüz yayınlanmamış bir değişikliğe dayanıyorsa ortaya çıkabilir. Core Blockly her çeyreğin son haftasında (üç ayda bir) yayınlanır.