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:

$ 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

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

Fixing a bug or implementing a feature will require you to write some new code.

We have a code style guide that outlines our guidelines for writing code for BeeWare.

Test-driven development¶

A good way to ensure your code is going to do what you expect it to, is to first write a test case to test for it. This test case should fail initially, as the code it is testing for is not yet present. You can then write the code changes needed to make the test pass, and know that what you've written is solving the problem you are expecting it to.

Run your code¶

Once your code is written, you need to ensure it runs. You'll need to manually run your code to verify it is doing what you expect. If you haven't already, you'll want to write a test case for your changes; as mentioned above, this test should fail if your code is commented out or not present.

You'll add your test case to the test suite, so it can be run alongside the other tests. The next step is to run the test suite.

Running tests and coverage¶

BeeWare uses tox to manage the testing process and pytest for its own test suite.

The default tox command includes running:

pre-commit hooks
towncrier release note check
documentation linting
test suite for available Python versions
code coverage reporting

This is essentially what is run by CI when you submit a pull request.

To run the full test suite, run:

macOSLinuxWindows

(.venv) $ tox

(.venv) $ tox

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

The full test suite can take a while to run. You can speed it up considerably by running tox in parallel, by running tox p (or tox run-parallel). When you run the test suite in parallel, you'll get less feedback on the progress of the test suite as it runs, but you'll still get a summary of any problems found at the end of the test run. You should get some output indicating that tests have been run. You may see SKIPPED tests, but shouldn't ever get any FAIL or ERROR test results. We run our full test suite before merging every patch. If that process discovers any problems, we don't merge the patch. If you do find a test error or failure, either there's something odd in your test environment, or you've found an edge case that we haven't seen before - either way, let us know!

In addition to the tests passing, this should report 100% test coverage.

Running test variations¶

Run tests for multiple versions of Python¶

By default, many of the tox commands will attempt to run the test suite multiple times, once for each Python version supported by BeeWare. To do this, though, each of the Python versions must be installed on your machine and available to tox's Python discovery process. In general, if a version of Python is available via PATH, then tox should be able to find and use it.

Run only the test suite¶

If you're rapidly iterating on a new feature, you don't need to run the full test suite; you can run only the unit tests. To do this, run:

macOSLinuxWindows

(.venv) $ tox -e py

(.venv) $ tox -e py

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

Run a subset of tests¶

By default, tox will run all tests in the unit test suite. When you're developing your new test, it may be helpful to run just that one test. To do this, you can pass in any pytest specifier as an argument to tox. These test paths are relative to the briefcase directory. For example, to run only the tests in a single file, run:

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

You'll still get a coverage report when running a part of the test suite - but the coverage results will only report the lines of code that were executed by the specific tests you ran.

Run the test suite for a specific Python version¶

By default tox -e py will run using whatever interpreter resolves as python on your machine. If you have multiple Python versions installed, and want to test a specific Python version from the versions you have installed, you can specify a specific Python version to use. For example, to run the test suite on Python 3.10, run:

macOSLinuxWindows

(.venv) $ tox -e py310

(.venv) $ tox -e py310

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

A subset of tests can be run by adding -- and a test specification to the command line.

Run the test suite without coverage (fast)¶

By default, tox will run the pytest suite in single threaded mode. You can speed up the execution of the test suite by running the test suite in parallel. This mode does not produce coverage files due to complexities in capturing coverage within spawned processes. To run a single python version in "fast" mode, run:

macOSLinuxWindows

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

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

A subset of tests can be run by adding -- and a test specification to the command line; a specific Python version can be used by adding the version to the test target (e.g., py310-fast to run fast on Python 3.10).

Code coverage¶

BeeWare maintains 100% branch coverage in its codebase. When you add or modify code in the project, you must add test code to ensure coverage of any changes you make.

However, BeeWare targets multiple platforms, as well as multiple versions of Python, so full coverage cannot be verified on a single platform and Python version. To accommodate this, several conditional coverage rules are defined in the tool.coverage.coverage_conditional_plugin.rules section of pyproject.toml (e.g., no-cover-if-is-windows can be used to flag a block of code that won't be executed when running the test suite on Windows). These rules are used to identify sections of code that are only covered on particular platforms or Python versions.

Of note, coverage reporting across Python versions can be a bit quirky. For instance, if coverage files are produced using one version of Python but coverage reporting is done on another, the report may include false positives for missed branches. Because of this, coverage reporting should always use the oldest version Python used to produce the coverage files.

Understanding coverage results¶

At the end of the coverage test output there should be a report of the coverage data that was gathered:

Name    Stmts   Miss Branch BrPart   Cover   Missing
----------------------------------------------------
TOPLAM 7540 0 1040 0 100,0%

This tells us that the test suite has executed every possible branching path in the code. This isn't a 100% guarantee that there are no bugs, but it does mean that we're exercising every line of code in the codebase.

If you make changes to the codebase, it's possible you'll introduce a gap in this coverage. When this happens, the coverage report will tell you which lines aren't being executed. For example, lets say we made a change to some/interesting_file.py, adding some new logic. The coverage report might look something like:

Adı Stmts Bayan Şube BrPart Kapak Eksik
--------------------------------------------------------------------------------
src/some/interesting_file.py 111 1 26 0 98,1% 170, 302-307, 320->335
--------------------------------------------------------------------------------
TOPLAM 7540 1 1726 0 99,9%

This tells us that line 170, lines 302-307, and a branch jumping from line 320 to line 335, are not being executed by the test suite. You'll need to add new tests (or modify an existing test) to restore this coverage.

Coverage report for host platform and Python version¶

You can generate a coverage report for your platform and version of Python. For example, to run the test suite and generate a coverage report on Python 3.10, run:

macOSLinuxWindows

(.venv) $ tox -m test310

(.venv) $ tox -m test310

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

Coverage report for host platform¶

If all supported versions of Python are available to tox, then coverage for the host platform can be reported by running:

macOSLinuxWindows

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

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

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

Coverage reporting in HTML¶

A HTML coverage report can be generated by appending -html to any of the coverage tox environment names, for instance:

macOSLinuxWindows

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

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

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

It's not just about writing tests!¶

Although we ensure that we test all of our code, the task isn't just about maintaining that level of testing. Part of the task is to audit the code as you go. You could write a comprehensive set of tests for a concrete life jacket… but a concrete life jacket would still be useless for the purpose it was intended!

As you develop tests, you should be checking that the core module is internally consistent as well. If you notice any method names that aren't internally consistent (e.g., something called on_select in one module, but called on_selected in another), or where the data isn't being handled consistently, flag it and bring it to our attention by raising a ticket. Or, if you're confident that you know what needs to be done, create a pull request that fixes the problem you've found.

///

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

/// details-abstract | 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.

/// warning | 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:



/// tab | macOS



```console
(venv) $ tox -e docs-live

LinuxWindows

(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 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:

- ./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.

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.