Araçları kullanma

Alabileceğimiz en değerli geri bildirimlerden biri, BeeWare araçlarını kullanmaya çalışan ve bir sorun ya da eksik bir özellik keşfeden kişilerden gelen geri bildirimlerdir. Araçları gerçek hayatta kullanırken karşılaşabileceğiniz zorlukları anlamak bizim için son derece yararlıdır.

Her zaman yapmak istediğiniz şeyi düşünün ve onu yapmaya çalışın. Eğer projenizi gerçekleştirebilirseniz, tebrikler! Her zaman istediğiniz şeye sahip oldunuz.

Ancak, başarılı olamadıysanız, neyin yanlış gittiğini bize bildirin. Eksik bir özellik mi vardı? Belgeler kafa karıştırıcı mıydı veya bazı yönlerden eksik miydi? Deneyimlerinizi paylaşmanız, planlama sürecimizi şekillendirmek için kullanabileceğimiz yararlı bilgiler sağlar.

Herhangi bir sorunla karşılaşırsanız, yeni bir tartışma konusu başlatın, çünkü bu yeni bir sorun veya özellik önerisinin başlangıcı olabilir.

Katkıda bulunan araç kullanımı

Yeni bir sorun bildir

İyi bir sorun veya hata raporu yazmak, bir sorunu giderme becerisinde büyük fark yaratabilir. BeeWare'ye iyi bir hata raporu göndermenin yolu aşağıda açıklanmıştır.

Mevcut sorunları ara

Yeni bir sorun bildirmeden önce, dizin içinde kendi sorununuzla eşleşen mevcut sorunları arayın. Sorununuzla eşleşen mevcut bir açık sorun varsa, o soruna deneyiminizle ilgili ek bilgiler içeren bir yorum ekleyin. Örneğin, sorunu farklı bir Python sürümünde veya farklı bir işletim sisteminde görüyorsanız, bu ek bilgiler sorunun etkisini veya nedenini belirlemede yardımcı olabilir.

Sorununuzla eşleşen kapalı bir sorun bulursanız, bu sorunun ne zaman kapatıldığını kontrol edin. Sorun çok yakın zamanda kapatılmışsa, bu muhtemelen hatanızın düzeltildiği ve bir sonraki sürümde düzeltileceği anlamına gelir. Sorun 4 aydan daha uzun bir süre önce kapatılmışsa, karşılaştığınız sorun, hata mesajı ne kadar benzer görünse de, muhtemelen farklı bir sorundur.

Gördüğünüz sorunla eşleşen bir sorun bulamazsanız, yeni bir sorun açmak uygun olabilir.

Tartışmayla başlayın

GitHub'da bir sorun bildirmeden önce, yaşadığınız sorunun gerçekten bir hata mı yoksa kurulumunuz veya sürecinizle ilgili bir sorun mu olduğunu sormak için bir tartışma başlatmayı düşünün. Belgelenmiş davranışla doğrudan çelişen bir davranış görmüyorsanız, doğrudan hata raporu göndermeden önce bir soru sormak faydalı olabilir. Bir sorun bulduğunuz ortaya çıkarsa, tartışma konusu kolayca bir soruna dönüştürülebilir.

Bir tartışma başlatmak, sorunu en uygun yerde bildirdiğinizden emin olmanıza da yardımcı olabilir. BeeWare kullanırken bir sorun yaşamış olabilirsiniz, ancak sorun BeeWare ekosistemindeki farklı bir projedeki bir hatadan kaynaklanıyor olabilir.

İyi bir hata raporu yazmak

Yeni bir sorun gerekliyse, mümkün olduğunca fazla ayrıntı sağlamak önemlidir. İyi bir hata raporu, hatayla ilgili olabilecek tüm bilgileri ve mümkün olan en küçük yeniden üretme örneğini içerir.

Çoğaltma örneği, hatayı sergilerken mümkün olduğunca kısa ve öz olmalıdır. Çok büyük bir örnek vermek, özellikle diğer kütüphanelere bağlıysa veya örneğin beklenen davranışı veya iç mantığı hakkında kapsamlı bilgi gerektiriyorsa, sorun gidermeyi önemli ölçüde zorlaştırır.

Mümkün olduğunca fazla ayrıntıya ihtiyacımız var. Bunlar arasında şunlar yer alır, ancak bunlarla sınırlı değildir:

• İşletim sistemi sürümünüz - mikro sürüme kadar (örneğin, macOS 15.7.2).
• Python sürümünüz, mikro sürümüne kadar (örneğin, 3.14.1).
• Python'u nasıl yüklediniz? Python.org adresinden mi indirdiniz? Homebrew mu kullandınız? uv? pyenv? conda? Başka bir şey mi?
• Kullandığınız BeeWare araçlarının belirli sürümü (örneğin, Toga 0.5.3). Geliştirme sürümünü kullanıyorsanız, hangi Git hash'i kullanıyorsunuz? "Mevcut ana dal" demek yeterli değildir, çünkü bu her gün değişebilir.
• Sorunu tetiklemek için yüklenmesi gereken diğer paketlerin belirli sürümleri. Bu bilgiyi sağlamak için python -m pip freeze komutunu çalıştırmanın sonuçlarını ekleyebilirsiniz.
• Bir günlük dosyası oluşturulmuşsa, tüm günlük dosyası.
• Bir yığın izleme oluşturulmuşsa, tüm yığın izlemeyi sağlayın. Yalnızca son hata mesajını vermeyin; yığın izlemenin tam bağlamı önemlidir. Bunu ekran görüntüsü olarak değil, metin biçiminde sağlamak en iyisidir.
• Soruna etki edebilecek bilgisayarınız veya ağ kurulumunuzla ilgili başka herhangi bir şey var mı? Bilgisayarınız eski veya yavaş mı? İş yerinde kullanılan, güvenlik duvarı, virüs tarayıcı veya başka kısıtlamalar bulunan bir bilgisayar mı? Ağınız özellikle yavaş mı? İşletim sisteminizi alışılmadık sistem varsayılanlarıyla mı çalıştırıyorsunuz (örneğin, çok büyük yazı tipi veya başka bir yardımcı teknoloji etkinleştirilmiş)?

Kalıpların dışında düşünmeye çalışın ve yaşadığınız soruna etki edebilecek her şeyi dahil etmeye çalışın. İhtiyacımız olandan fazlasını verirseniz, ihtiyacımız olmayanları kolayca göz ardı edebiliriz. Sizin atladığınız bir şeyi biz bulamayız.

Minimal bir örnek

Hata raporunun en önemli kısmı, minimum yeniden üretim örneğidir. Üçüncü bir tarafın yeniden üretim örneğinizin talimatlarını okuyup, bu talimatları takip ederek aynı sorunu gözlemleyebilmesi mümkün olmalıdır. Bu, sorunu gösteren bir örnek proje sunmak veya daha da iyisi, önceden var olan bir örnek (mevcut kod tabanının bir parçası olan bir öğretici veya örnek proje gibi) kullanmak anlamına gelebilir.

Projenizin tamamı minimal bir yeniden üretim örneği değildir. Minimal bir yeniden üretim örneği, sorunu oluşturmak için kesinlikle gerekli olmayan hiçbir kod içermemelidir. Yeniden üretim örneğini oluştururken acımasız olun - sorunu oluşturmak için bir düğme gerekli değilse, o düğmeyi dahil etmeyin.

Çoğu zaman, bu minimal yeniden üretim örneğini geliştirme süreci sorunun kaynağını ortaya çıkarır, çünkü minimal örnek oluşturma eylemi, sorunun nedenini tam olarak bulmanızı gerektirir; bu, koddaki bir hata mı, yoksa yanlış varsayımlardan veya API kullanımından mı kaynaklanıyor?

Ayrıca, yeniden üretme talimatlarında açık olmalısınız. "Örnek uygulamayı kapatın" demek, penceredeki kapat düğmesine tıklamak, menüden "çıkış" seçeneğini seçmek veya terminalde Control-C tuşlarına basmak anlamına gelebilir. Raporunuz, sorunu yeniden üretmek için yapılması gerekenler konusunda hiçbir belirsizliğe yer bırakmamalıdır.

Raporun sunulması

Navigate to the project issues list, click the "New issue" button, and choose "Bug report" to begin the process.

Sorun şablonundaki tüm bölümleri doldurmanız gerekir. Şablonu, gerekli bilgileri sağlamanıza yardımcı olmak için bir kılavuz olarak sunuyoruz. Unutmayın, şablonda istenen bilgilerin ötesinde daha fazla bilgi sağlayabilirsiniz (ve sağlamalısınız!), ancak en azından şablonda yer alan tüm bilgilere ihtiyacımız vardır.

Kod eklerken, BeeWare öğreticisi gibi mevcut bir örnekle yeniden üretebiliyorsanız, bir bağlantı sağlayabilirsiniz. Aksi takdirde, raporun içine kodu ekleyin. Kod, Markdown biçiminde olmalıdır; bir kod bloğunun başında ve sonunda üç ters eğik çizgi (```) bulunmalıdır.

Uzun bir metin bloğu eklemeniz gerekiyorsa, aşağıdaki sözdizimini kullanarak onu daraltılmış içerik haline getirebilirsiniz:

<details>
<summary>Collapsed content title</summary>
Long block of text.
</details>

Mümkün olduğunca fazla bilgi sağladıktan sonra, "Oluştur" düğmesine tıklayarak raporu gönderin.

Yeni bir özellik önerin

BeeWare için bir iyileştirme fikriniz var - bu fikri değerlendirilmek üzere nasıl sunabilirsiniz?

Araştırmanızı yapın

İlk adım, BeeWare sorun izleyicisinde mevcut özellik sorunları ("geliştirme" etiketli sorunlar), belgeleme sorunları ("belgeleme" etiketli sorunlar) veya Tartışma konuları arayarak bu fikrin daha önce önerilip önerilmediğini kontrol etmektir. Önerilmişse ve eklemek istediğiniz yeni bir bağlam veya fikir varsa, bunları mevcut konuya ekleyin. Araştırmanızda yardıma ihtiyacınız varsa, BeeWare Discord üzerindeki #dev kanalında soru sorabilirsiniz. Size mevcut konuları gösterebilir, bilmediğiniz bağlamları sağlayabilir veya fikrinizi ilk bakışta alakalı görünmeyen başka bir fikirle ilişkilendirebiliriz.

Fikri tartışın

Fikrinizle ilgili mevcut herhangi bir referans bulamazsanız, bir Tartışma başlığı açın. Fikrinizin amacını ve kullanım örneğini genel hatlarıyla açıklayın. Özelliğin uygulanması durumunda nasıl görüneceğine dair düşüncelerinizi de ekleyin. Örneğin, API'nin genel şekli, özelliğin görsel görünümü veya eklenecek belge gibi. Uygunsa, fikrinizin farklı platformlarda nasıl ortaya çıkacağına dair yaptığınız araştırmaları da eklemelisiniz.

Tartışma başlığı açıldığında, BeeWare ekibi ve topluluğun geri kalanı yanıt verecektir. Çekirdek ekip, iki iş günü içinde fikriniz hakkında en azından ilk izlenimlerini paylaşmayı hedefleyecektir. Bir fikir özellikle karmaşıksa, daha ayrıntılı bir analiz bir haftaya kadar sürebilir. Tatiller ve konferanslar gibi olaylar bu sürelerin biraz daha uzamasına neden olabilir.

Bu, fikriniz hakkında bir sohbete katılma fırsatınızdır. Daha fazla ayrıntı veya bağlam isteyebiliriz. Topluluğun diğer üyeleri de tartışmaya katılarak farklı bakış açıları, öneriler veya karşı öneriler sunabilir. Bu tartışmanın sonucu, sonraki adımları belirleyecektir.

Tüm fikirlerin kabul edilmeyeceğini anlamak önemlidir. Bu sürecin bir teklifle başlamasının nedeni, tüm işi yapıp sonra da değişikliğinizin kabul edilmeyecek bir nedeni olduğunu öğrenmenizi önlemektir.

Bu, bunun iyi bir fikir olmadığı anlamına gelmez! Uygulanamamasının teknik nedenleri olabilir. Örneğin, aşağıdaki durumlarda bir fikri reddedebiliriz:

• Desteklenen tüm platformlarda güvenilir bir şekilde uygulanması zor veya imkansız olacaktır; veya
• Bakımı zor olacaktır veya bakım için yaygın olarak bulunmayan teknoloji veya yazılıma erişim gerekecektir; veya
• Niş bir kitleye hizmet ediyor, ancak diğer kullanıcılara önemli bir ek yük getiriyor.

Fikrinizin uygun olmadığına karar verirsek, bu mutlaka fikrinizden vazgeçmeniz gerektiği anlamına gelmez. Belirli bir fikri reddedebiliriz, ancak aynı özelliği harici bir kütüphane olarak sürdürmenizi sağlayacak bir eklenti arayüzü veya başka bir uzantı noktası eklemeye çok daha açık olabiliriz. Bu şekilde, özelliği elde edebilir, ancak özelliğin belirli bakım sorunları veya sınırlamaları projenin kendisi için bir kısıtlama haline gelmez.

Resmi özellik talebine dönüştür

Tartışma, bir özelliğin şekli konusunda bir konsensüse ulaştığında, beeware sorun izleyicisinde, tartışmayı özetleyen ve bağlam için tartışmaya bağlantı veren yeni bir özellik isteği sorunu oluşturabilirsiniz.

Özellik önerinizi kendiniz uygulamak zorunda değilsiniz; önerdiğiniz şeyin ayrıntılarını içeren bir sorun bildirimi açabilirsiniz. Ancak, sorunu bildirmekle, bunun sizin için uygulanacağı anlamına gelmez. Aynı özellikle ilgilenen başka bir kişi, ister başka bir topluluk üyesi ister çekirdek ekip olsun, bu sorunu ele almasını beklemeniz gerekir; ancak bunun gerçekleşeceği garanti edilemez. Uygulamanın garanti edilmesini istiyorsanız, bunu kendiniz uygulamalı veya başkasına uygulatmak için ödeme yapmalısınız.