Bir sorunu düzeltme

BeeWare [bilinen sorunların] listesini takip eder. Bu sorunların herhangi biri üzerinde çalışılması gereken adaylardır.

Bu liste çeşitli şekillerde filtrelenebilir. Örneğin, platformlara göre filtreleyerek, test edebileceğiniz platformları etkileyen sorunlara odaklanabilirsiniz; veya dokümantasyon hataları gibi sorun türüne göre filtreleyebilirsiniz. Ayrıca iyi ilk sorunlar için bir filtre de vardır. Bunlar, nedeni bilinen sorunlar olarak tanımlanan ve düzeltmesinin nispeten basit olması gerektiğine inandığımız sorunlardır (ancak analizimizde yanılıyor olabiliriz).

Bir sorun 6 aydan daha eskiyse, sorunun çözülmüş olması oldukça olasıdır, bu nedenle ilk adım, sorunu yeniden oluşturabileceğinizi doğrulamaktır. Hata raporunda verilen bilgileri kullanarak sorunu yeniden oluşturmaya çalışın. Sorunu yeniden oluşturamazsanız, bulduklarınızı sorunla ilgili bir yorum olarak bildirin ve başka bir sorun seçin.

Sorunu yeniden oluşturabilirseniz, sorunu gidermeye çalışın! Özelliği uygulayan kod kombinasyonunu belirleyin ve neyin doğru çalışmadığını bulmaya çalışın.

Sorunu çözemeseniz bile, süreç sırasında keşfettiğiniz her şeyi sorunla ilgili yorum olarak bildirmek faydalı olacaktır. Sorunun kaynağını bulabilirseniz, ancak çözümü bulamazsanız, bu bilgi genellikle platform hakkında daha fazla bilgiye sahip birinin sorunu çözmesi için yeterli olacaktır. Sorun henüz iyi bir yeniden üretme örneği (sorunu yeniden üretmekten başka bir şey yapmayan küçük bir örnek uygulama) sağlamıyorsa, böyle bir örnek sağlamak çok yardımcı olabilir.

Bir sorun düzeltmesine katkıda bulunmak

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:

Python 3.8.10 (varsayılan, 20 Temmuz 2020, 16:16:00)

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:

Python 3.8.10 (varsayılan, 20 Temmuz 2020, 16:16:00)

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/<kullanıcı adınız>/beeware.git

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

BeeWare deposunu çatallayın ve ardından:

$ git clone https://github.com/<kullanıcı adınız>/beeware.git

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

BeeWare deposunu çatallayın ve ardından:

C:\...>git clone https://github.com/<kullanıcı adınız>/beeware.git

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

Yukarı akış deposu ayarlayın

Çatalınızı klonladıktan sonra, BeeWare deposunu upstream uzak olarak ekleyin. Bu, yerel klonunuza orijinal depoya bir referans sağlar ve zaman içinde güncellemeleri senkronize etmeyi kolaylaştırır.

Ayrıca, Toga ve Briefcase gibi araçların doğru sürüm numaralarını çözebilmesi için upstream etiketlerine de ihtiyacınız olacak:

macOSLinuxWindows

$ git remote add upstream https://github.com/beeware/beeware.git
$ git fetch --tags upstream

$ git remote add upstream https://github.com/beeware/beeware.git
$ git fetch --tags upstream

C:\...>git remote add upstream https://github.com/beeware/beeware.git
C:\...>git fetch --tags upstream

Çatalınızın da bu etiketleri içermesini istiyorsanız, bunları ekleyebilirsiniz:

$ git push --tags

Bu, daha sonra yeni bir klon oluşturursanız ve etiketlerin çatallarınızdan kullanılabilir olmasını istiyorsanız yararlı olabilir.

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

Sorunu yeniden oluşturun

Sorun yoksa, sorunu çözemezsiniz. Bu nedenle, sorunu çözmek için önce sorunu yeniden oluşturmak gerekir. Yazılımda, sorunlar genellikle "hata" olarak adlandırılır ve sorunlar genellikle "hata raporları" olarak adlandırılır.

Birisi bir hata raporu gönderdi. Rapor eden kişinin tarif ettiği adımların, bildirilen hataya yol açtığını doğrulamanız gerekir. Raporda tarif edilenleri aynen uygulayarak aynı sonucu elde edebiliyor musunuz? Eğer edemiyorsanız, bunun nedenini bulmanız gerekir.

Koddaki hatalar

İdeal bir durumda, hatayı bildiren kişiyle aynı kurulumunuz olacak, adımları takip edecek ve hatayı açıklanan şekilde yeniden oluşturabileceksiniz. Ancak çoğu durumda bu kadar basit olmayacaktır. Çoğu hata raporu sadece belirsiz açıklamalar ve belirsiz koşullar içerir. Sorun, birçok hatanın, etkileşim şekli, çeşitli ön koşullar, işletim sistemi, işletim sistemi sürümü, CPU mimarisi veya kullanıcının makinesinin eski ve yavaş mı yoksa yeni ve hızlı mı olduğu gibi ilgili koşullar kümesine göre değişmesidir. Hata ile ilgili durum hakkında ne kadar fazla bilgiye sahip olursak o kadar iyidir. Rapor eden kişinin sağladığı koşulları yeniden oluşturmaya çalışın. Bunu yapamıyorsanız, bir sonraki adımınız hatayı rapor eden kişiden daha fazla bilgi istemek olabilir.

Bir hatayı yeniden üretmenin en iyi yolu, sorunu hala gösteren mümkün olan en küçük örneği kullanmaktır. Çoğu zaman, rapor edenler minimum düzeyde geçerli bir örnek sunmazlar; herhangi bir örnek sunarlarsa, bu örnek "gerçek dünya" uygulamalarından doğrudan kopyalanır. Amacınız, raporu sorunu gösteren mümkün olan en basit forma indirgemek olacaktır. En iyi yeniden üretme örneği, mümkün olan en küçük programdır. Bu indirgeme, gerçek sorunun ne olduğunu belirlediği için yararlıdır. Herkes minimal örneği alıp çalıştırabilir ve açıklanan hatayı gözlemleyebilir.

Dokümantasyon hataları

Dokümantasyon hataları farklı şekillerde ortaya çıkabilir. Biçimlendirmeyle ilgili sorunlar, görüntüleme sorunlarına yol açabilir. Bazen bu bir hata bile olmayabilir; kişi belgeleri yanlış okumuş veya gerçekten bir hata yapmış olabilir. Bu, belgelerde bir sorun olmadığı anlamına gelmez. İçerik belirsiz veya kesin olmayabilir ve bu da karışıklığa veya yanlış yorumlamaya yol açabilir. Tartışılması gereken bir kavram, tamamen belgelenmemiş olduğu için tartışılmamış olabilir.

Bir dokümantasyon sorunu için hata bildirildiğinde, bildirilen sorunun gerçekten hala mevcut olup olmadığını doğrulamak isteyeceksiniz. Görüntüleme sorunları durumunda, sorunu yeniden oluşturabilmek için dokümantasyonu oluşturmanız gerekecektir. İçerik sorunları ise, hiç kimsenin güncelleme göndermediğini doğrulamak için okunması gereken bir konudur.

Sorunu güncelle

Triaj sürecinin son adımı, sorunla ilgili bir yorum bırakarak bulgularınızı belgelemektir.

Sorunu tam olarak anlatıldığı şekilde yeniden oluşturabilirseniz, söylemeniz gereken tek şey budur. Orijinal rapor eden kişinin tarif ettiği şekilde aynı sorunu gördüğünüzü doğruladığınızı belirten bir yorum bırakın.

Ek bilgi sağlayabiliyorsanız, bu bilgilerin ayrıntılarını da ekleyin. Bu, sorunu farklı bir işletim sisteminde veya ilgili yazılımların farklı sürümlerinde yeniden oluşturabilme veya orijinal rapordan farklı olan diğer herhangi bir bilgi olabilir.

Orijinal raporda, raporu yeniden oluşturmak için ihtiyaç duyduğunuz ayrıntılar eksikse, bu ayrıntıları ekleyin. Bu, orijinal raporda yer almayan işletim sistemi veya sürüm ayrıntılarını, daha eksiksiz günlükleri veya yığın izlerini veya sorunu yeniden oluşturmak için gereken işlemlerin tam sırasına ilişkin daha net talimatları içerebilir. Sorunu yeniden oluşturmak için daha basit bir yol geliştirdiyseniz (veya orijinal raporu hazırlayan kişi bir yeniden oluşturma örneği sağlamadıysa), bu yeniden oluşturma yönteminin ayrıntılarını ekleyebilirsiniz.

Sorunu yeniden oluşturabilirseniz, denediğiniz şeyleri ayrıntılı olarak açıklayan bir yorum da bırakın. Sorunun nerede olmadığını bilmek, nerede olduğunu bilmek kadar önemlidir, çünkü bu, olası nedenleri daraltmaya yardımcı olur. Sorunu neden yeniden oluşturamadığınızla ilgili herhangi bir teoriniz varsa (örneğin, kullanım hatası olduğunu düşünüyorsanız veya sorunun son işletim sistemi güncellemesiyle çözüldüğünü düşünüyorsanız), bu spekülasyonu yorumunuza ekleyin.

Son olarak, çekirdek ekibe önerilerde bulunabilirsiniz. Orijinal raporun hatalı olduğunu düşünüyorsanız, sorunun kapatılmasını önerin; sorunun nedeni hakkında bir teoriniz varsa, bunu da önerebilirsiniz. Yorumlarınız, çekirdek ekibin sorunu bir sonraki adıma nasıl taşıyacağını belirlemesine yardımcı olacaktır.

Sorunun giderilmesi için kodda değişiklik yapılması gerekiyorsa:

Kod yazın, çalıştırın ve test edin

Bir hatayı düzeltmek veya bir özelliği eklemek için yeni kod yazmanız gerekecektir.

BeeWare için kod yazma kurallarımızı özetleyen bir kod stil kılavuzumuz bulunmaktadır.

Test odaklı geliştirme

Kodunuzun beklediğiniz şekilde çalışacağından emin olmanın iyi bir yolu, öncelikle bunu test etmek için bir test senaryosu yazmaktır. Test edilen kod henüz mevcut olmadığı için bu test senaryosu başlangıçta başarısız sonuç vermelidir. Ardından, testin başarılı olması için gereken kod değişikliklerini yazabilir ve yazdığınız kodun, beklediğiniz sorunu çözdüğünden emin olabilirsiniz.

Kodunu çalıştır

Kodunuzu yazdıktan sonra, kodun çalıştığından emin olmanız gerekir. Kodun beklediğiniz şekilde çalıştığını doğrulamak için onu manuel olarak çalıştırmanız gerekecektir. Henüz yapmadıysanız, yaptığınız değişiklikler için bir test senaryosu yazmanızda fayda var; yukarıda da belirtildiği gibi, kodunuz yorum satırına alınmışsa veya mevcut değilse bu test başarısız olmalıdır.

Test senaryonuzu test paketine ekleyeceksiniz, böylece diğer testlerle birlikte çalıştırılabilecektir. Bir sonraki adım, test paketini çalıştırmaktır.

Testleri çalıştırma ve kapsama oranı

BeeWare test sürecini yönetmek için tox'yi, kendi test paketini ise pytest'yi kullanır.

Varsayılan tox komutu aşağıdakileri içerir:

• pre-commit kancaları
• towncrier sürüm notu kontrolü

• belge denetimi

• mevcut Python sürümleri için test paketi

• kod kapsamı raporlaması

Bir çekme isteği gönderdiğinizde CI tarafından çalıştırılan işlem temel olarak budur.

Tüm test paketini çalıştırmak için şunu girin:

macOSLinuxWindows

(.venv) $ tox

(.venv) $ tox

(.venv) C:\...>tox

Test paketinin tamamının çalıştırılması biraz zaman alabilir. tox komutunu paralel olarak çalıştırarak veya tox p (ya da tox run-parallel) komutunu kullanarak bu süreci önemli ölçüde hızlandırabilirsiniz. Test paketini paralel olarak çalıştırdığınızda, testler devam ederken ilerleme durumuna ilişkin daha az geri bildirim alırsınız, ancak test çalışmasının sonunda tespit edilen sorunların bir özetini yine de görürsünüz. Testlerin çalıştırıldığını belirten bir çıktı almalısınız. SKIPPED testlerini görebilirsiniz, ancak hiçbir zaman FAIL veya ERROR test sonuçları almamalısınız. Her yamayı birleştirmeden önce tam test paketimizi çalıştırırız. Bu işlemde herhangi bir sorun tespit edilirse, yamayı birleştirmeyiz. Bir test hatası veya başarısızlığı bulursanız, ya test ortamınızda garip bir durum vardır ya da daha önce görmediğimiz bir sınır durumu bulmuşsunuzdur - her iki durumda da bize bildirin!

Testlerin başarılı olmasının yanı sıra, bu durum %100 test kapsamı olarak raporlanmalıdır.

Test varyasyonlarını çalıştırma

Python'un farklı sürümleri için testler çalıştırın

Varsayılan olarak, tox komutlarının çoğu, BeeWare tarafından desteklenen her Python sürümü için birer kez olmak üzere test paketini birden fazla kez çalıştırmaya çalışır. Ancak bunun için, her bir Python sürümünün bilgisayarınızda yüklü olması ve tox'nin Python keşif işlemi tarafından algılanabilmesi gerekir. Genel olarak, bir Python sürümü PATH aracılığıyla erişilebilirse, tox bu sürümü bulup kullanabilmelidir.

Yalnızca test paketini çalıştır

Yeni bir özellik üzerinde hızlı bir şekilde yineleme yapıyorsanız, test paketinin tamamını çalıştırmanıza gerek yoktur; sadece birim testlerini çalıştırabilirsiniz. Bunu yapmak için şu komutu çalıştırın:

macOSLinuxWindows

(.venv) $ tox -e py

(.venv) $ tox -e py

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

Testlerin bir kısmını çalıştır

Varsayılan olarak, tox komutu birim test paketindeki tüm testleri çalıştırır. Yeni bir test geliştirirken, sadece o testi çalıştırmak faydalı olabilir. Bunu yapmak için, pytest komutuna argüman olarak [herhangi bir (https://docs.pytest.org/en/latest/how-to/usage.html#specifying-which-tests-to-run) belirteci]tox geçirebilirsiniz. Bu test yolları, briefcase dizinine göre görelidir. Örneğin, tek bir dosyadaki testleri çalıştırmak için şunu girin:

macOSLinuxWindows

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) C:\...>tox -e py -- tests/path_to_test_file/test_some_test.py

Test paketinin bir bölümünü çalıştırdığınızda yine de bir kapsama raporu alacaksınız; ancak kapsama sonuçları, yalnızca çalıştırdığınız belirli testler tarafından yürütülen kod satırlarını gösterecektir.

Belirli bir Python sürümü için test paketini çalıştır

Varsayılan olarak tox -e py, bilgisayarınızda python olarak çözümlenen herhangi bir yorumlayıcı kullanılarak çalıştırılır. Bilgisayarınızda birden fazla Python sürümü yüklüyse ve yüklü sürümlerden belirli bir Python sürümünü test etmek istiyorsanız, kullanılacak Python sürümünü belirtebilirsiniz. Örneğin, test paketini Python 3.10 üzerinde çalıştırmak için şu komutu çalıştırın:

macOSLinuxWindows

(.venv) $ tox -e py310

(.venv) $ tox -e py310

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

Bir test kümesi, komut satırına -- ve bir test tanımı eklenerek çalıştırılabilir.

Test paketini kapsama analizi yapmadan çalıştır (hızlı)

Varsayılan olarak, tox test dizisini tek iş parçacıklı modda çalıştırır. Test dizisini paralel olarak çalıştırarak yürütme süresini kısaltabilirsiniz. Bu modda, başlatılan işlemler içinde kapsama oranını yakalamanın karmaşıklığı nedeniyle kapsama dosyaları oluşturulmaz. Tek bir Python sürümünü "hızlı" modda çalıştırmak için şunu çalıştırın:

macOSLinuxWindows

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

(.venv) C:\...>tox -e py-fast

Bir test kümesi, komut satırına -- ve bir test tanımı eklenerek çalıştırılabilir; belirli bir Python sürümü, test hedefine sürüm eklenerek kullanılabilir (örneğin, Python py310-fast üzerinde hızlı çalıştırmak için 3.10).

Kod kapsamı

BeeWare kod tabanında %100 test kapsamı sağlar. Projeye kod eklediğinizde veya mevcut kodu değiştirdiğinizde, yaptığınız değişikliklerin test kapsamına alınmasını sağlamak için test kodu eklemeniz gerekir.

Ancak, BeeWare hem birden fazla platformu hem de Python'un çeşitli sürümlerini hedeflediğinden, tam kapsam tek bir platform ve Python sürümünde doğrulanamaz. Bunu telafi etmek için, tool.coverage.coverage_conditional_plugin.rules bölümünde birkaç koşullu kapsama kuralı tanımlanmıştır (örneğin, pyproject.toml Windows'ta test takımını çalıştırırken yürütülmeyecek bir kod bloğunu işaretlemek için kullanılabilir). Bu kurallar, yalnızca belirli platformlarda veya Python sürümlerinde kapsanan kod bölümlerini tanımlamak için kullanılır.

Dikkat edilmesi gereken bir nokta, farklı Python sürümleri arasında kod kapsama raporlamasının biraz tuhaf sonuçlar verebilmesidir. Örneğin, kapsama dosyaları bir Python sürümüyle oluşturulmuş ancak raporlama başka bir sürümde yapılmışsa, raporda gözden kaçan dallara ilişkin yanlış pozitif sonuçlar yer alabilir. Bu nedenle, kod kapsama raporlamasında her zaman kapsama dosyalarının oluşturulmasında kullanılan en eski Python sürümü kullanılmalıdır.

Kapsam sonuçlarını anlamak

Kapsama testi çıktısının sonunda, toplanan kapsama verilerine ilişkin bir rapor bulunmalıdır:

Adı    Hesaplar   Kayıp Şube BrPart   Kapsam   Eksik
 ---------------------------------------------------
 TOPLAM    7540 0   1040 0  100,0%

Bu, test takımının koddaki tüm olası dallanma yollarını çalıştırdığını gösterir. Bu, hata olmadığına dair %100 bir garanti değildir, ancak kod tabanındaki her satırı test ettiğimiz anlamına gelir.

Kod tabanında değişiklik yaparsanız, bu kapsama alanında bir boşluk oluşabilir. Böyle bir durumda, kapsama raporu hangi satırların çalıştırılmadığını size gösterecektir. Örneğin, some/interesting_file.py içinde bir değişiklik yapıp yeni bir mantık eklediğimizi varsayalım. Kapsama raporu şunun gibi görünebilir:

Adımlar   Hata   Dal   BrPart  Kapsam   Eksik
 -------------------------------------------------------------------------------
 src/some/interesting_file.py 111 1     26 0  %98,1   170, 302-307, 320->335
 -------------------------------------------------------------------------------
 TOPLAM 7540 1   1726 0  %99,9

Bu, 170. satırın, 302-307. satırların ve 320. satırdan 335. satıra atlayan bir dalın test paketi tarafından çalıştırılmadığını gösteriyor. Bu kapsama oranını geri kazanmak için yeni testler eklemeniz (veya mevcut bir testi değiştirmeniz) gerekecek.

Ana platform ve Python sürümü için uyumluluk raporu

Kullandığınız Python platformu ve sürümü için bir kapsama raporu oluşturabilirsiniz. Örneğin, test takımını çalıştırıp Python 3.10 için bir kapsama raporu oluşturmak için şu komutu çalıştırın:

macOSLinuxWindows

(.venv) $ tox -m test310

(.venv) $ tox -m test310

(.venv) C:\...>tox -m test310

Ana platform için kapsama raporu

Python'un desteklenen tüm sürümleri tox için mevcutsa, ana platformun kapsama oranı şu komut çalıştırılarak raporlanabilir:

macOSLinuxWindows

(.venv) $ tox p -m test-platform

(.venv) $ tox p -m test-platform

(.venv) C:\...>tox p -m test-platform

HTML'de kapsam raporlaması

Kapsam -html ortam adlarının herhangi birinin sonuna tox eklenerek bir HTML kapsam raporu oluşturulabilir; örneğin:

macOSLinuxWindows

(.venv) $ tox -e coverage-platform-html

(.venv) $ tox -e coverage-platform-html

(.venv) C:\...>tox -e coverage-platform-html

Mesele sadece test yazmak değil!

Her ne kadar tüm kodlarımızı test ettiğimizden emin olsak da, bu iş sadece bu test düzeyini korumaktan ibaret değildir. Bu işin bir parçası da, kod üzerinde çalışırken onu denetlemektir. Somut bir can yeleği için kapsamlı bir test dizisi yazabilirsiniz… ama somut bir can yeleği yine de asıl amacına uygun olarak kullanılamaz!

Testler geliştirirken, çekirdek modülün içsel olarak da tutarlı olup olmadığını kontrol etmelisiniz. İçsel olarak tutarlı olmayan yöntem adları fark ederseniz (örneğin, bir modülde on_select olarak adlandırılan, ancak başka bir modülde on_selected olarak adlandırılan bir şey) veya verilerin tutarlı bir şekilde işlenmediği durumlar varsa, bunu işaretleyin ve bir bilet açarak bize bildirin. Ya da ne yapılması gerektiğini bildiğinizden eminseniz, bulduğunuz sorunu düzelten bir çekme isteği oluşturun.

Sorunun giderilmesi için belgelerde değişiklik yapılması gerekiyorsa:

Belgeleri oluşturun

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:

BİLGİ    -  [11:18:51] http://127.0.0.1:8000/ adresinde hizmet veriliyor

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

(fiil) $ tox -e docs-all

(fiil) $ 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 yazın

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:

- ./dizin/yolu/*

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:

- [Yeni belgem](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.

Katkınızı göndermeye hazır olduğunuzda:

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.