Yeni bir özelliğin uygulanması

Öneri süreci sona erdiğinde, yeni bir özellik için eksiksiz bir tasarıma sahip olmalısınız. Bu, yazmaya başlama zamanının geldiği anlamına gelir!

Özelliğiniz platform özelinde bir uygulama gerektiriyorsa, teklif sürecinde bu fikrin tüm platformlarda uygulanabilir olduğu doğrulanmış olmalıdır. Ancak, yeni bir özelliği ilk kez uygulayan kişi olarak, tüm platformlar için yeni özelliği uygulamaktan sorumlu değilsiniz. Testler dahil olmak üzere en az bir platform için eksiksiz bir uygulama sağlamanız gerekir. Diğer platformlar için, "stub" uygulaması sağlamanız gerekir. Bu uygulama, temel arayüz tanımını sağlar, ancak NotImplementedError oluşturur veya davranışın o platformda uygulanmadığını belirten bir günlük mesajı görüntüler.

Yeni bir özelliğin uygulanmasının önemli bir parçası, bu özelliğin tam olarak belgelendirilmesini sağlamaktır. Bu, en azından API belgelerinin mevcut olmasını sağlamak anlamına gelir; ancak bir kullanım kılavuzu veya konu kılavuzu eklemek de gerekebilir.

Yeni işlevsellik katkısı

Geliştirme ortamı kurun

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

Önkoşullar

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

macOSLinuxWindows

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

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

$ python3 --version

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

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

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

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

$ python3 --version

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

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

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

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

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

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

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

Geliştirme ortamınızı kurun

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

BeeWare deposunu klonla

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

macOSLinuxWindows

BeeWare deposunu çatallayın ve ardından:

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

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

BeeWare deposunu çatallayın ve ardından:

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

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

BeeWare deposunu çatallayın ve ardından:

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

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

Sanal ortam oluşturun

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

macOSLinuxWindows

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

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

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

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

BeeWare'yi yükle

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

macOSLinuxWindows

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

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

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

Ön taahhüt etkinleştir

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

macOSLinuxWindows

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

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

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

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

Şubeden çalışmak

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

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

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

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

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

macOSLinuxWindows

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

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

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

Kapsam genişlemesini önleyin

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

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

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

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

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

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

Yeni özelliği uygulayın

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.

///

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

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.