Belgelerin eklenmesi¶

Dünyanın en iyi yazılımına sahip olabilirsiniz, ancak kimse onu nasıl kullanacağını bilmiyorsa ne anlamı var? Belgeler her zaman geliştirilebilir ve sizin yardımınıza ihtiyacımız var!

Dokümantasyon formları¶

BeeWare'nin belgeleri MkDocs ve Markdown kullanılarak yazılmıştır. Belgeleri yapılandırmak için Diataxis çerçevesini takip etmeyi hedefliyoruz.

Diataxis çerçevesi, dört "biçim"teki dokümantasyonu tanımlamaktadır:

Öğretici - Belirli bir proje hedefi olan, rehberli bir öğrenme deneyimi.
Nasıl yapılır kılavuzu - Okuyucuyu belirli bir hedefe veya sonuca yönlendiren talimatlar.
Konu kılavuzu - Temel kavramların açık bir şekilde açıklanarak tek bir fikrin tartışılması.
Referans - Belirli API'lerin veya diğer arayüzlerin teknik açıklamaları.

Herhangi bir dokümantasyon katkısına başlamadan önce, hangi formun en uygun olduğunu belirlemek önemlidir. Birçok dokümantasyon önerisi ilk olarak "X hakkında bir eğitim" talebi olarak tanımlanır, ancak çoğu durumda aslında gerekli olan şey, nasıl yapılır kılavuzu, konu kılavuzu veya geliştirilmiş referans bilgidir.

Örnek olarak, kurabiye pişirmeyle ilgili dokümantasyon yazma görevini ele alalım.

Öğretici¶

Öğretici, özellikle yeni başlayanlara yönelik bir giriş niteliğindedir ve amacı okuyucuyu sıfırdan başlayarak bitmiş bir ürüne ulaştırmaktır. Öğretici, çok spesifik talimatlar ve öğreticinin adımlarını bağlam içine yerleştiren ayrıntılı açıklamalar gerektirir. Okuyucunun açıklanan araçla ilgili deneyimi hakkında hiçbir varsayımda bulunmamalısınız, ancak temel Python bilgisine sahip olduğunu varsaymak mantıklıdır.

Öğretici, okuyucunun açıklananları başarıyla uyguladığını doğrulayabileceği düzenli kontrol noktaları içermelidir. Her kontrol noktasında başarı kriterleri açık olmalıdır. Bilinen başarısızlık durumları, okuyucunun karşılaşabileceği olası hatalar veya sorunların açıklamaları da dahil olmak üzere açıkça belirtilmelidir. Okuyucunun yaptığı eylemlerin sonucunda değişen şeyler, açıkça belli olsa bile belirtilmelidir. Özellikle en iyi uygulamaları veya ortak süreçleri belirlemeye çalışıyorsanız, tekrarlamalar teşvik edilmelidir. İç işleyişin açıklamalarından ve aynı sonuca giden alternatif yollardan kaçınılmalıdır.

Kurabiye pişirme öğreticisi, sadece bir tariften daha fazlasıdır. Öğreticideki talimatlar, daha önce hiç pişirme yapmamış kişiler (örneğin çocuklar) için anlaşılır olmalı ve deneyimli bir fırıncının doğal kabul edeceği şeyleri (örneğin şeker ve tereyağını krema haline getirme, fırını önceden ısıtma veya kurabiyeleri yemeden önce ne kadar süre soğumaya bırakılması gerektiği gibi) açıklamalıdır. Öğreticinin amacı kurabiye yapmak değil, pişirmenin temellerini aktarmaktır. Sonuçta ortaya çıkan kurabiye, birisini öğreticiyi denemeye ikna eden lezzetli bir ikramdır.

Nasıl yapılır kılavuzu¶

Bir kullanım kılavuzu, teorik açıklamalardan ziyade belirli bir gerçek dünya kullanım örneğine ve pratik sonuçlara odaklanmalıdır. Bir öğretici kılavuzdan farklı olarak, mevcut araçlara bir miktar aşina olduğunuzu varsayabilirsiniz. Okuyucu, kılavuzu baştan sona takip edebilmeli ve hedefe ulaşabilmelidir, ancak bunu yapmak için bazı mevcut bilgilere ihtiyaç duyabilir. Kılavuzun hedefine ulaşmak için izlenmesi gereken bir dizi somut talimat veya mantıklı adım içermelidir.

Yemek kitabındaki bir tarif, nasıl yapılır kılavuzunun iyi bir örneğidir. Çikolatalı kurabiye tarifleri çok çeşitlidir ve hepsi ortak özellikler taşır, ancak herhangi bir tarifin başından sonuna kadar takip edilebilmesi ve tutarlı bir sonuç vermesi gerekir. İyi bir çikolatalı kurabiye tarifi, farklı şeker veya un türlerinin göreceli avantajlarına girmez veya temel teknik veya süreçlerle ilgili ayrıntılı talimatlar vermez; okuyucunun pişirme konusunda temel bilgilere sahip olduğunu varsayarak, sadece bir parti kurabiye pişirmek için gerekli malzemeleri ve talimatları içerir.

Konu kılavuzu¶

Konu kılavuzu, tek bir konuyu veya fikri açıklar. Örnek kodlar veya talimatlar içerebilir, ancak genel bir kavramın üst düzey bir resmini sunmaya odaklanır. Görüşler ve alternatif bakış açıları içerebilir, ancak kılavuzun belirli konusuna odaklanılması gerekir.

Kurabiye pişirmeyle ilgili bir konu kılavuzu, kurabiye tarihini bir fırın ürünü olarak inceleyebilir, endüstriyel süreçlerin ev yapımı kurabiyelerden farklı kurabiye türleri ortaya çıkarmasını keşfedebilir veya kurabiyelerin dengeli bir diyete nasıl dahil edilebileceğini önerebilir. Tek başına, kurabiye pişirmek istiyorsanız takip etmek için çok yararlı bir belge olmayabilir, ancak pişirme konusunda bilgili bir kişinin mevcut bir kurabiye tarifini başarıyla özelleştirmesini sağlayacak arka plan bilgisi sağlayabilir.

Referans¶

Referans belgeleri, araç kütüphanesinin çalışmasının ayrıntılarını açıklayan, bilgi odaklı belgelerdir. Bu belgeler genellikle kodun kendisinden oluşturulabilir, ancak iyi bir API belgesi daha fazla açıklama ve bağlam gerektirebilir. Bazen kullanım örnekleri içerebilir, ancak ayrıntılı açıklamalardan kaçınılmalıdır.

Fırıncılıkta bir referans kılavuzu, kullanılabilecek şeker türlerini açıklayabilir ve fırıncılıkta kullanıldıklarında özelliklerini ayrıntılı olarak anlatabilir. Şekerle ilgili gerçekleri anlatır, ancak şeker türleri arasında seçim yapma konusunda daha geniş bir tartışma, bir nasıl yapılır kılavuzu veya konu kılavuzunun konusu olmalıdır. Çoğu paketlenmiş gıdada bulunan besin bilgileri, referans belgesi olarak kabul edilir.

Belge stili¶

BeeWare'nin belgeleri, belgeleme stil kılavuzu içinde belirtilen yönergeleri takip eder. Bu kılavuz, temel stil ve biçimlendirme ile yazım denetimi sürecini içerir. Ayrıca, referans bağlantı sözdizimi, kod bloklarıyla çalışma ipuçları ve görüntü işleme gibi çeşitli Markdown sözdizimi ayrıntılarını da kapsar.

Katkıda bulunan belgeler¶

Yeni dokümantasyon önerisi

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.

Geliştirme ortamı kurun

BeeWare'ye katkıda bulunmak için bir geliştirme ortamı kurmanız gerekir.

Önkoşullar¶

Aşağıdaki önkoşulları yüklemeniz gerekecektir.

macOSLinuxWindows

BeeWare Python 3.10+ gerektirir. Ayrıca sanal ortamları yönetmek için bir yönteme (örneğin venv) ihtiyacınız olacaktır.

Yüklediğiniz Python sürümünü şu komutu çalıştırarak doğrulayabilirsiniz:

$ python3 --version

Birden fazla Python sürümü yüklü ise, python3 ifadesini belirli bir sürüm numarasıyla (örneğin, python3.13) değiştirmeniz gerekebilir.

Son zamanlarda piyasaya sürülen Python sürümlerinden (yani, 3.14.0 gibi ".0" veya ".1" mikro sürüm numarasına sahip sürümler) kaçınmanızı öneririz. Bunun nedeni, macOS'ta Python'u desteklemek için gereken araçların genellikle son zamanlarda piyasaya sürülen kararlı Python sürümleri için mevcut olmamasıdır.

BeeWare Python 3.10+ gerektirir. Ayrıca sanal ortamları yönetmek için bir yönteme (örneğin venv) ihtiyacınız olacaktır.

Yüklediğiniz Python sürümünü şu komutu çalıştırarak doğrulayabilirsiniz:

$ python3 --version

Birden fazla Python sürümü yüklü ise, python3 ifadesini belirli bir sürüm numarasıyla (örneğin, python3.13) değiştirmeniz gerekebilir.

Son zamanlarda piyasaya sürülen Python sürümlerinden (yani, 3.14.0 gibi ".0" veya ".1" mikro sürüm numarasına sahip sürümler) kaçınmanızı öneririz. Bunun nedeni, Linux'ta Python'u desteklemek için gereken araçların genellikle son zamanlarda piyasaya sürülen kararlı Python sürümleri için mevcut olmamasıdır.

BeeWare Python 3.10+ gerektirir. Ayrıca sanal ortamları yönetmek için bir yönteme (örneğin venv) ihtiyacınız olacaktır.

Yüklediğiniz Python sürümünü şu komutu çalıştırarak doğrulayabilirsiniz:

C:\...>py -3 --version

Birden fazla Python sürümü yüklü ise, -3 ifadesini belirli bir sürüm numarasıyla (örneğin, -python3.13) değiştirmeniz gerekebilir.

Son zamanlarda piyasaya sürülen Python sürümlerinden (yani, 3.14.0 gibi ".0" veya ".1" mikro sürüm numarasına sahip sürümler) kaçınmanızı öneririz. Bunun nedeni, Windows'ta Python'u desteklemek için gereken araçların genellikle son zamanlarda piyasaya sürülen kararlı Python sürümleri için mevcut olmamasıdır.

Geliştirme ortamınızı kurun¶

BeeWare için geliştirme ortamınızı kurmanın önerilen yolu, bir sanal ortam kullanmak ve ardından BeeWare'nin geliştirme sürümünü ve bağımlılıklarını yüklemektir.

BeeWare deposunu klonla¶

Ardından, GitHub'daki BeeWare sayfasına gidin ve henüz yapmadıysanız, deposu kendi hesabınıza fork edin. Ardından, fork'unuzdaki "<> Kod" düğmesine tıklayın. Bilgisayarınızda GitHub masaüstü uygulaması yüklüyse, "GitHub Masaüstü ile aç" seçeneğini seçebilirsiniz; aksi takdirde, sağlanan HTTPS URL'sini kopyalayın ve komut satırını kullanarak depoyu bilgisayarınıza kopyalayın:

macOSLinuxWindows

BeeWare deposunu çatallayın ve ardından:

$ git clone https://github.com/<your username>/beeware.git

(GitHub kullanıcı adınızı girin)

BeeWare deposunu çatallayın ve ardından:

$ git clone https://github.com/<your username>/beeware.git

(GitHub kullanıcı adınızı girin)

BeeWare deposunu çatallayın ve ardından:

C:\...>git clone https://github.com/<your username>/beeware.git

(GitHub kullanıcı adınızı girin)

Sanal ortam oluşturun¶

Sanal ortamı kurmak ve pip'yi yükseltmek için şunu çalıştırın:

macOSLinuxWindows

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

C:\...>cd beeware
C:\...>py -3 -m venv .venv
C:\...>.venv\Scripts\activate
(.venv) $ python -m pip install -U pip

Komut isteminizin önünde artık (.venv) önekine sahip olmalıdır.

BeeWare'yi yükle¶

Artık kaynak koduna sahip olduğunuza göre, (https://setuptools.pypa.io/en/latest/userguide/development_mode.html)'yi geliştirme ortamınıza [düzenlenebilir kurulum]BeeWare yapabilirsiniz. Aşağıdaki komutu çalıştırın:

macOSLinuxWindows

(.venv) $ python -m pip install -U -e . --group dev

(.venv) $ python -m pip install -U -e . --group dev

(.venv) C:\...>python -m pip install -U -e . --group dev

Ön taahhüt etkinleştir¶

BeeWare basit sorunları tespit etmek ve kod biçimlendirmesini standartlaştırmak için pre-commit adlı bir araç kullanır. Bunu, herhangi bir git commit işlemini tamamlamadan önce bir dizi kod linter'ı otomatik olarak çalıştıran bir git hook yükleyerek yapar. Pre-commit'i etkinleştirmek için şunu çalıştırın:

macOSLinuxWindows

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) C:\...>pre-commit install
pre-commit installed at .git/hooks/pre-commit

Artık BeeWare üzerinde hacklemeye hazırsınız!

Şubeden çalışmak

Değişiklik üzerinde çalışmaya başlamadan önce, bir dal oluşturduğunuzdan emin olun. Varsayılan olarak, depo çatalınızı klonladığınızda, main dalında kontrol edileceksiniz. Bu, BeeWare dalının doğrudan bir kopyasıdır.

main dalından bir çekme isteği gönderebilirsiniz, ancak bunu yapmamanız tercih edilir. Neredeyse doğru olan bir çekme isteği gönderirseniz, çekme isteğinizi inceleyen çekirdek ekip üyesi, küçük bir değişiklik isteyen geri bildirimde bulunmak yerine gerekli değişiklikleri yapabilir. Ancak, çekme isteğinizi main dalından gönderirseniz, inceleyenler değişiklik yapamazlar.

Ana dal üzerinde çalışmak, ilk çekme isteğinizi tamamladıktan sonra sizin için de zorluk yaratır. İkinci bir çekme isteği üzerinde çalışmak istiyorsanız, ikinci katkınızı dayandırabileceğiniz, yukarı akış projesinin ana dalının "temiz" bir kopyasına sahip olmanız gerekir; ilk katkınızı main dalından yaptıysanız, artık bu temiz sürüme sahip değilsinizdir.

Bunun yerine, değişikliklerinizi bir özellik dalında yapmalısınız. Özellik dalı, yaptığınız değişikliği tanımlamak için basit bir ada sahiptir. Örneğin, Windows 11'de derleme sorunlarına neden olan bir hatayı düzeltiyorsanız, fix-win11-build özellik dalı oluşturabilirsiniz. Hatanız bildirilmiş belirli bir sorunla ilgiliyse, dal adında bu sorun numarasını belirtmek de yaygın bir uygulamadır (ör. fix-1234).

fix-win11-build özellik dalı oluşturmak için şunu çalıştırın:

macOSLinuxWindows

(.venv) $ git switch -c fix-win11-build

(.venv) $ git switch -c fix-win11-build

(.venv) C:\...>git switch -c fix-win11-build

Kapsam genişlemesini önleyin

"Kapsam genişlemesi", tek bir katkı ile çözülen sorunların veya uygulanan özelliklerin listesi, çalışmaya başlandığında amaçlananın çok ötesine geçtiğinde meydana gelir. Basit bir sorunla başlarsınız; yakından ilişkili bir sorun keşfedersiniz ve bu düzeltmeyi de dahil etmeye karar verirsiniz; sonra bir üçüncü… farkına varmadan, 5 sorunu kapatan ve düzinelerce dosya içeren 3 yeni özellik ekleyen bir çekme isteği elde edersiniz.

Kapsam genişlemesi herkesin başına gelir. Bu, deneyimli geliştiriciler için çok tanıdık bir kavramdır; hepimiz bunu birçok kez yaptık ve bununla birlikte gelen tüm sorunları yaşadık.

Kapsam genişlemesini önlemek için çok pratik nedenler vardır. Katkı ne kadar büyük olursa, onunla çalışmak o kadar zorlaşır. Sınır durumlarını veya potansiyel sorunları belirlemek zorlaşır, bu da katkının genel kalitesinin düşebileceği anlamına gelir. İnceleme yapan kişinin birden fazla, potansiyel olarak ilgisiz bağlamla uğraşması gerektiğinde incelemeler de daha zor hale gelir. Daha büyük bir katkı, daha fazla inceleme yorumu anlamına gelir ve katkıda bulunan kişi olarak birden fazla inceleme dizisini takip etmek zorlaşabilir. GitHub deneyiminiz bile olumsuz etkilenir - PR'nin boyutu büyüdükçe GitHub'ın kullanıcı arayüzü yavaşlar, bu da GitHub arayüzü üzerinden dosyalarda gezinmek ve inceleme yorumları bırakmak giderek zorlaşır.

Katkınıza, orijinal teklifin veya hata raporunun açıkça bir parçası olmayan herhangi bir şey eklemek için bir neden bulduğunuzda, kapsam genişlemesi yaşayıp yaşamadığınızı düşünmelisiniz. Ayrı ayrı uygulanabilecek iki farklı özellik var mı? Bir özellik, bilinen bir sınırlama veya hata ile uygulanabilir mi ve bu hata, takip eden bir çekme isteğinde düzeltilebilir mi? Hata düzeltmesinin bir kısmı diğerinden bağımsız mı? Değişikliğin bir kısmı, orijinal katkıyı değiştirmeden dışarıda bırakılabiliyorsa, muhtemelen öyle yapılmalıdır.

Yazılım geliştirme her zaman aşamalı bir iyileştirme sürecidir. Her bir katkı, birleştirilmesinin sonucunda kod tabanını daha iyi bir duruma getirmelidir, ancak hataları veya özelliklerin bazı kısımlarını gelecekte iyileştirilmek üzere bırakmak tamamen kabul edilebilir bir durumdur. Bu, bir çekme isteğini bağımsız olarak incelenebilecek birden fazla parçaya bölmek veya başka birinin sorunu araştırıp çözebilmesi için bir sorun kaydı oluşturmak anlamına gelebilir.

Her bir katkının kapsamını sınırlamak, siz dahil olmak üzere tüm katılımcılara yardımcı olur. Yorumcularınız ve hatta siz bile bunu takdir edeceksiniz.

Bina belgeleri

BeeWare belgelerinde herhangi bir değişiklik yapmadan önce, mevcut belgeleri oluşturabileceğinizi doğrulamanız yararlı olacaktır.

Python 3.13 yorumlayıcısının yüklü olması ve yolunuzda kullanılabilir olması gerekir (yani, python3.13 bir Python 3.13 yorumlayıcısını başlatmalıdır).

BeeWare belgeleri oluşturmak için tox kullanır. Aşağıdaki tox komutları, projenin kök dizininde bulunan tox.ini dosyasıyla aynı konumdan çalıştırılmalıdır.

Canlı dokümantasyon önizlemesi¶

Belgelerin hızlı düzenlenmesini desteklemek için, BeeWare "canlı önizleme" moduna sahiptir.

Canlı önizleme uyarılarla oluşturulacaktır!

Canlı sunum, belgelerinizdeki güncellemeleri yinelemek için kullanılabilir. Güncelleme işlemi sırasında, bir işaretleme sorunu ortaya çıkabilir. WARNING olarak kabul edilen sorunlar, standart bir derlemenin başarısız olmasına neden olur, ancak canlı sunum, derlemeyi sürdürürken konsol çıktısında uyarılar gösterecek şekilde ayarlanmıştır. Bu, canlı önizlemeyi yeniden başlatmanıza gerek kalmadan yineleme yapmanızı sağlar.

WARNING ile ERROR farklıdır. ERROR olarak kabul edilen bir sorun ortaya çıkarsa, canlı hizmet başarısız olur ve yeniden başlatılması gerekir. WARNING sorunu çözülene kadar yeniden başlatılmaz.

Canlı sunucuyu başlatmak için:

macOSLinuxWindows

(venv) $ tox -e docs-live

(venv) $ tox -e docs-live

(venv) C:\...>tox -e docs-live

Bu, belgeleri oluşturacak, belgeleri sunmak için bir web sunucusu başlatacak ve belge kaynağında herhangi bir değişiklik olup olmadığını dosya sistemini izleyecektir.

Sunucu başlatıldığında, konsol çıktısında aşağıdakine benzer bir mesaj göreceksiniz:

INFO    -  [11:18:51] Serving on http://127.0.0.1:8000/

Bir tarayıcı açın ve verilen URL'ye gidin. Artık belgeleri yinelemeye başlayabilirsiniz. Bir değişiklik algılanırsa, belgeler yeniden oluşturulur ve değiştirilen sayfayı görüntüleyen tüm tarayıcılar otomatik olarak yenilenir.

docs-live ilk adımdır

Canlı sunucuyla çalışmak için docs-live komutunu çalıştırmak, ilk yineleme için tasarlanmıştır. Pull isteği göndermeden önce her zaman yerel bir derleme çalıştırmalısınız.

Yerel yapı¶

Yinelemeyi tamamladıktan sonra, belgelerin yerel bir derlemesini yapmanız gerekir. Bu derleme işlemi, herhangi bir işaretleme sorunu varsa başarısız olacak şekilde tasarlanmıştır. Bu, canlı sunucuda gözden kaçırmış olabileceğiniz her şeyi yakalamanızı sağlar.

Yerel bir derleme oluşturma¶

Yerel bir derleme oluşturmak için:

macOSLinuxWindows

(venv) $ tox -e docs

(venv) $ tox -e docs

(venv) C:\...>tox -e docs

Bu derlemenin çıktısı, projenin kök dizinindeki _build dizininde olacaktır.

Yerel olarak çevrilmiş bir derleme oluşturma¶

BeeWare'nin belgeleri birçok dile çevrilmiştir. İngilizce belgelerdeki güncellemeler, diğer dil sürümlerinde sorunlara yol açabilir. Pull isteği göndermeden önce tüm sürümlerin çalıştığını doğrulamak önemlidir.

Mevcut tüm çevirilerin bir derlemesini oluşturmak için:

macOSLinuxWindows

(venv) $ tox -e docs-all

(venv) $ tox -e docs-all

(venv) C:\...>tox -e docs-all

Her dil yapısının çıktısı, ilişkili _build/html/<languagecode> dizininde olacaktır. Burada <languagecode>, belirli dil ile ilişkili iki veya beş karakterli dil kodudur (örneğin, Fransızca için fr, İtalyanca için it vb.).

Tek bir derlemede bir sorun bulursanız, tox -e docs-<languagecode> komutunu çalıştırarak o derlemeyi ayrı olarak çalıştırabilirsiniz. Örneğin, yalnızca Fransızca belgeleri derlemek için şunu çalıştırın:

macOSLinuxWindows

(venv) $ tox -e docs-fr

(venv) $ tox -e docs-fr

(venv) C:\...>tox -e docs-fr

Tek dilli derlemenin çıktısı _build dizininde olacaktır.

Belgelerin linting'i¶

Derleme işlemi Markdown sorunlarını tespit eder, ancak BeeWare stil ve biçimlendirme için "linting" olarak bilinen bazı ek kontroller gerçekleştirir. Lint kontrollerini çalıştırmak için:

macOSLinuxWindows

(venv) $ tox -e docs-lint

(venv) $ tox -e docs-lint

(venv) C:\...>tox -e docs-lint

Bu, belgelerin aşağıdakileri içermediğini doğrular:

ölü bağlantılar
yanlış yazılmış kelimeler

Bir kelimenin geçerli yazımı yanlış yazılmış olarak tanımlanırsa, kelimeyi docs/spelling_wordlist içindeki listeye ekleyin. Bu, kelimeyi yazım denetleyicisinin sözlüğüne ekleyecektir. Bu listeye eklerken şunu unutmayın:

Programlamaya özgü konuşma dilinde kullanılan bazı kelimeler (örneğin, "apps") ve isimlerin fiil olarak kullanılması (örneğin, "scrollable") dışında, ABD İngilizcesini tercih ediyoruz.
Ürün adına yapılan her türlü atıfta, ürünün tercih edilen büyük harf kullanımı kullanılmalıdır. (ör. "macOS", "GTK", "pytest", "Pygame", "PyScript").
Bir terim "kod olarak" kullanılıyorsa, sözlüğe eklenmek yerine kelime olarak (like this) alıntılanmalıdır.

Dokümantasyon yazma

BeeWare, belgelerinize katkı sağlamak için izlemeniz gereken adımlar şunlardır.

Mevcut belgelerin güncellenmesi¶

Mevcut belgeleri düzenliyorsanız, dosyayı /docs/en dizininde bulmanız gerekir. Dosya yapısı sayfa yapısını takip eder, bu nedenle belge URL'sini kullanarak dosyayı bulabilirsiniz.

Yeni dokümantasyon ekleme¶

Yeni bir belge ekliyorsanız, birkaç adım daha vardır.

Belgeyi docs/en dizinindeki uygun konumda oluşturmanız gerekir. Tartışma için, new_doc.md dosya adıyla yeni bir belge eklediğinizi varsayalım.

Ardından, yeni dosyanızı eklemek için docs/en/SUMMARY.md dosyasını güncellemeniz gerekir. SUMMARY.md temel olarak docs/en dizin yapısını yansıtacak şekilde düzenlenmiştir, ancak daha da önemlisi, sol kenar çubuğunun yapısını doğrudan belirler. new_doc.md eklemek istediğiniz bölümü bulursanız, joker karakter içeren bir yol listeleniyorsa SUMMARY.md içinde herhangi bir değişiklik yapmanız gerekmez. Örneğin:

- ./path/to/directory/*

new_doc.md eklemek istediğiniz bölüm, tek tek Markdown bağlantılarının bir listesi ise, bağlantınıza açık bir bağlantı eklemeniz gerekir. Örneğin:

- [My new document](new_doc.md)

Dokümantasyonunuzu yazma¶

Artık istediğiniz dosyayı editörünüzde açabilir ve yazmaya başlayabilirsiniz.

BeeWare için dokümantasyon yazma kurallarımızı özetleyen bir dokümantasyon stil kılavuzu bulunmaktadır.

Değişiklik notu ekle

Birçok BeeWare aracı, her sürüm için sürüm notlarının oluşturulmasına yardımcı olmak için towncrier kullanır. İlgili araçlardan birine çekme isteği gönderdiğinizde, bu isteğin bir değişiklik notu içermesi gerekir. Bu değişiklik notu, yapılan değişikliği açıklayan sürüm notlarında bir giriş haline gelir.

Her çekme isteği, çekme isteği tarafından uygulanan değişikliğin kısa bir açıklamasını içeren changes/ dizininde en az bir dosya içermelidir. Değişiklik notu, <id>.<fragment type>.md biçiminde bir dosyada Markdown biçiminde olmalıdır. Önerdiğiniz değişiklik, mevcut bir sorun numarası olan bir hatayı düzeltecek veya bir özelliği uygulayacaksa, kimlik numarası o biletin numarası olacaktır. Değişikliğin karşılık gelen bir sorunu yoksa, PR numarası kimlik numarası olarak kullanılabilir. Pull isteğini gönderene kadar bu PR numarasını bilemeyeceksiniz, bu nedenle ilk CI geçişi towncrier kontrolünde başarısız olacaktır; değişiklik notunu ekleyin ve bir PR güncellemesi gönderin, ardından CI geçmelidir.

Beş parça türü vardır:

feature: PR, daha önce mümkün olmayan yeni bir davranış veya yetenek ekler (örneğin, yeni bir paketleme formatı için destek eklemek veya mevcut bir paketleme formatına yeni bir özellik eklemek);
bugfix: PR, mevcut uygulamadaki bir hatayı düzeltir;
doc: PR, dokümantasyon açısından önemli bir iyileştirmedir;
doc: PR, dokümantasyon açısından önemli bir iyileştirmedir;
doc: PR, dokümantasyon açısından önemli bir iyileştirmedir;

Değişiklik notundaki bu açıklama, derinlemesine teknik bir açıklama veya uygulama detayı değil, kullanıcının bakış açısından değişikliğin üst düzey bir "pazarlama" özeti olmalıdır. Bu, bir taahhüt mesajından farklıdır - taahhüt mesajı, gelecekteki geliştiricilerin bir değişikliğin gerekçesini takip edebilmeleri için ne yapıldığını açıklar; değişiklik notu ise, iç işleyiş hakkında bilgi sahibi olmayabilecek kullanıcıların yararına bir açıklamadır.

Örneğin, proje adlandırmasıyla ilgili bir hatayı düzelttiyseniz, commit mesajı şöyle olabilir:

Rakamlarla başlayan proje adlarını yasaklamak için daha güçlü bir düzenli ifade kontrolü uygulayın.

İlgili değişiklik notu şu şekilde olacaktır:

Proje adları artık sayı ile başlayamaz.

Bazı PR'ler birden fazla özellik sunar ve birden fazla hatayı düzeltir veya birden fazla geriye dönük uyumsuz değişiklik yapar. Bu durumda, PR'da birden fazla değişiklik notu dosyası olabilir. Aynı kimliğe sahip iki parça türünü ilişkilendirmeniz gerekiyorsa, sayısal bir son ek ekleyebilirsiniz. Örneğin, PR 789, bilet 123 ile açıklanan bir özellik ekledi, bilet 234 ile açıklanan bir hatayı kapattı ve ayrıca geriye dönük uyumsuz iki değişiklik yaptıysa, 4 değişiklik notu dosyanız olabilir:

123.feature.md
234.bugfix.md
789.removal.1.md
789.removal.2.md

towncrier ve parça türleri hakkında daha fazla bilgi için Haber Parçaları bölümüne bakın. Ayrıca, changes deposunun BeeWare dizininde mevcut haber parçaları örneklerini de görebilirsiniz. Bu klasör boşsa, bunun nedeni BeeWare'nin yakın zamanda yeni bir sürüm yayınlamış olmasıdır; değişiklik notu dosyaları silinir ve her sürümde sürüm notları güncellenmek üzere birleştirilir. Gerekli yorum stilini görmek için bu dosyaya bakabilirsiniz; değişiklik notlarınızı nasıl biçimlendireceğinizi görmek için son birleştirilen PR'lere bakabilirsiniz.

Çekme isteği gönder

Tüm değişikliklerinizi kaydettikten sonra, çekme isteği göndermeye hazırsınız demektir. Sorunsuz bir inceleme süreci için, atmanız gereken birkaç adım vardır.

Ön taahhüt ile çalışma¶

Herhangi bir değişiklik yaptığınızda, pre-commit otomatik olarak çalışır. Commit ile ilgili herhangi bir sorun bulunursa, bu durum commit'inizin başarısız olmasına neden olur. Mümkün olduğunda, pre-commit bulduğu sorunları düzeltmek için gerekli değişiklikleri yapar. Aşağıdaki örnekte, ruff kontrolü tarafından bir kod biçimlendirme sorunu bulunmuştur:

macOSLinuxWindows

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) C:\...>git add some/interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

Bu durumda, ruff sorunu otomatik olarak düzeltti; böylece, ön onay kontrollerinin sonucunda değiştirilen tüm dosyaları yeniden ekleyebilir ve değişikliği yeniden onaylayabilirsiniz. Ancak, bazı kontroller manuel değişiklikler yapmanızı gerektirecektir. Bu değişiklikleri yaptıktan sonra, değiştirilen tüm dosyaları yeniden ekleyin ve yeniden onaylayın.

macOSLinuxWindows

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) C:\...>git add some\interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

Her şey tamamlandığında, commit işleminin tamamlandığını belirten bir mesaj göreceksiniz ve git log'unuzda commit'iniz en son eklenen olarak görünecektir. Artık GitHub'a push yapmaya hazırsınız.

Değişikliklerinizi GitHub'a gönderin ve çekme isteğinizi oluşturun.¶

GitHub'a ilk kez gönderdiğinizde, yeni bir çekme isteği oluşturmak için sizi doğrudan GitHub sayfasına yönlendiren bir URL verilecektir. URL'yi takip edin ve çekme isteğinizi oluşturun.

Aşağıda, URL'nin vurgulandığı push, üzerinde neler bekleyebileceğinize dair bir örnek gösterilmektedir.

macOSLinuxWindows

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) C:\...>git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

Mevcut dalı daha önce GitHub'a gönderdiyseniz, URL'yi tekrar almayacaksınız. Ancak, PR oluşturma URL'sine ulaşmanın başka yolları da vardır:

Yukarı akış deposuna gidin, "Pull Request'ler" ve ardından "Yeni pull request" seçeneğine tıklayın ve pull request'inizi göndermek istediğiniz kaynağı seçin.
Son zamanlarda push yaptıysanız, upstream deposuna gidin, dosya listesinin üzerinde deponun "son zamanlarda push yapıldığını" belirten başlığı bulun ve "Karşılaştır ve pull isteği" düğmesini tıklayın.
GitHub CLI gh pr create komutunu kullanın ve istemleri doldurun.
GitHub CLI gh pr create --web komutunu kullanarak bir web tarayıcısını PR oluşturma sayfasına açın.

Bu seçeneklerden herhangi biri, yeni çekme isteğinizi oluşturmanıza olanak tanır.

GitHub CLI: gh

GitHub, terminalinizden (https://cli.github.com/) komutu aracılığıyla GitHub'ın birçok özelliğine erişmenizi sağlayan [GitHub CLI]gh sunar. GitHub CLI belgeleri tüm özellikleri kapsar.

Çekme isteği içeriği¶

Bir çekme isteği başlığı bilgilendirici, açık ve özlü olmalıdır. Mümkünse kısa tutmaya çalışın, ancak gerekirse daha uzun başlıklar da kabul edilebilir. İyi bir PR başlığı, herhangi bir bağlam bilgisi olmayan bir kişiye, PR'nizin hangi hatayı veya özelliği uyguladığını makul ölçüde sağlam bir fikir vermelidir.

PR açıklaması, PR'daki değişiklikleri açıkça yansıtmalıdır. Konuyla ilgili hiçbir bilgisi olmayan bir kişi bile açıklamanızı okuyup, değişikliğin neden yapıldığına dair nispeten eksiksiz bir anlayışa sahip olabilmelidir. Şakalar, deyimler, konuşma dili ve tümü büyük harf kullanımı veya aşırı noktalama gibi gereksiz biçimlendirmelerden kaçının. Bu, PR'ınızda neler olup bittiğine dair basit bir açıklama olmalıdır ve bu tür şeylerden kaçınmak, açıklamanın diğerleri için daha erişilebilir olmasını sağlar.

PR'da yer alan değişikliklerin bir parçası olmayan herhangi bir çoğaltma durumu veya kullandığınız herhangi bir test rejimi varsa, bunlar açıklanmalı ve PR'ya dahil edilmelidir. Açıklama, bunların nasıl çalıştırılacağını ve istenen sonucu elde etmek için ne yapılması gerektiğini içermelidir.

Pull isteğiniz #1234 numaralı sorunu çözecekse, pull isteğinizin açıklamasına Fixes #1234 metnini eklemelisiniz. Bu, pull isteği birleştirildiğinde sorunun otomatik olarak kapatılmasını sağlar. Aynı #1234 sözdizimini kullanarak diğer tartışmalara, sorunlara veya pull isteklerine başvurabilirsiniz. Numaraya - ön eki ekleyerek farklı bir depodaki bir soruna başvurabilirsiniz; örneğin, python/cpython#1234 CPython deposundaki 1234 numaralı soruna başvurur.

Sürekli entegrasyon¶

Sürekli entegrasyon veya CI, çekme isteğiniz üzerinde otomatik kontroller gerçekleştirme sürecidir. Bu, kodun doğru biçimde biçimlendirildiğinden emin olmak gibi basit kontroller içerebilir; ancak test paketini çalıştırmak ve belgeleri oluşturmak da buna dahildir.

CI hatalarına neden olabilecek birçok değişiklik vardır. Genel olarak, CI'yı geçemeyen bir PR'yi incelemeyeceğiz. Bir çekme isteği oluşturursanız ve CI başarısız olursa, geçene kadar incelemeye başlamayacağız. Değişiklikleriniz bir hataya neden olursa, nedenini araştırmak ve sorunu çözmek sizin sorumluluğunuzdadır.

CI başarısız olduğunda, başarısız bağlantılar PR sayfasının altında, "Bazı kontroller başarılı olmadı" başlığı altında gösterilir. Başarısız kontroller listesi, başarılı kontroller de varsa tüm kontroller listesinin en üstünde gösterilir. Başarısızlık bağlantısını tıklarsanız, günlüğe yönlendirilirsiniz. Günlük, genellikle başarısızlığın nedenini anlamak için ihtiyacınız olan tüm bilgileri sağlar. Günlüğü okuyun ve başarısızlığın nedenini anlamaya çalışın, ardından sorunu çözmek için gerekli işlemleri yapın.

Bazen, CI kontrolü, yaptığınız değişikliklerle ilgisi olmayan nedenlerle başarısız olabilir. Bunun nedeni, CI kontrolünü çalıştıran makinede bir sorun olması veya CI kontrolünün kararsız olması olabilir. Bir hata görürseniz ve bunun yaptığınız değişikliklerle ilgisi olmadığına emin iseniz, PR'nize bu konuyla ilgili bir yorum ekleyin, biz de bunu inceleyeceğiz.

Yeni bir CI çalıştırmasını tetiklemek için, dallarınıza yeni değişiklikleri aktarmanız gerekir.

CI'nın geçmesi için yardıma ihtiyacınız olan bir durumla karşılaşırsanız, PR'ye bir yorum bırakarak bize bildirin, size yardımcı olmak için elimizden geleni yapacağız.

pre-commit ve towncrier kontrolleri

pre-commit veya towncrier kontrollerinden herhangi biri başarısız olursa, CI kontrollerinin geri kalanının çoğunun çalışması engellenir. Tüm kontroller çalıştırılmadan önce ilgili sorunları çözmeniz gerekir.

CI kaynaklarımız sınırlıdır. Her dala push yaptığınızda CI'nın başlayacağını anlamak önemlidir. Bir dizi değişiklik yapacaksanız, bu değişiklikleri yerel olarak yapıp hepsini bir kerede push etmek daha iyidir. CI, bir gruptaki en son commit üzerinde çalışacak ve CI sistemimizdeki yükü en aza indirecektir.

PR'ınızı gönderme işlemi, CI'yı geçene kadar tamamlanmış sayılmaz veya neden geçemediğine dair bir açıklama sunabilirsiniz.