Genel Bakış

Kod ve dokümantasyondaki tüm değişiklikler submitted adresine bir çekme isteği aracılığıyla Proje için GitHub deposu.

Çoğu projenin, özel ayrıntılar içeren özel bir katkı kılavuzu vardır ya da belirli katkı türlerini içermelidir. Bu dokümantasyon Read the Docs sayfasında bulunabilir. Örneğin, Evrak Çantası'nın documentation katkı içerir her ikisi için de kılavuzlar kod ve dokümantasyon.

Tüm gönderimler [BeeWare Kuralları]'na uygun olmalıdır. Davranış] (/community/behavior/code-of-conduct/).

Değişiklik Notları

Başta Evrak Çantası ve Toga olmak üzere bazı BeeWare projeleri, her bir Çekme talebi bir değişiklik notu ile birlikte gönderilir. Bu değişiklik notları şunlardır Proje için yeni bir sürüm kesildiğinde bir araya getirilerek yeni sürüm için sürüm notları.

BeeWare, [Towncrier] (https://towncrier.readthedocs.io/en/stable/) adresini kullanarak değişiklik notlarını yönetin.

Bir değişiklik notu dosyası changes dizininde oluşturulmalı ve bu format kullanılarak adlandırılmıştır:

<PR/Issue #>.<Change Type>.rst

Örneğin, GitHub sorunu #42'yi düzelten bir çekme isteği şu şekilde adlandırılır 42.bugfix.rst. Eğer bir çekme isteği belirli bir sorunu varsa, bunun yerine çekme isteği numarası kullanılabilir. Şunları yapmanız gerekebilir bir çekme isteği almak için değişiklik notu olmadan çekme isteği oluşturun numarası tahsis edin, ardından değişiklik notunu içeren bir güncellemeyi yeni tahsis edilen çekme isteği numarası.

Değişiklik notu için değişiklik türleri aşağıdakilerden biri olmalıdır:

  • özellik
  • bugfix
  • doc
  • kaldırma
  • misc

Kullanıcıları etkilemeyen değişiklikler için misc türü ayrılmıştır ve sürüm notlarında belirtilmesine gerek yoktur. Küçük tipografik düzeltmeler dokümantasyonda, CI yapılandırmasında güncellemeler ve hata düzeltmeleri için henüz resmi olarak yayınlanmamış özellikler şunlara örnektir işaretleri kullanılarak tanımlanabilecek özellikler.

Bir değişiklik notu tek satırlık bir metin olmalı ve üst düzey bir bilgi sağlamalıdır kullanıcı perspektifinden değişikliğin özeti, derinlemesine değil teknik açıklama veya uygulama detayı. Aşağıdakilerden farklıdır taahhüt mesajı. Bir commit mesajı ne yapıldığını açıklar, böylece gelecekteki geliştiriciler bir değişikliğin gerekçesini takip edebilir. Bir değişiklik notu yeni kabiliyet açısından tanımlanan "kullanıcıya dönük" bir açıklamadır. değişimin bir sonucu olarak mevcut olan. Şunları düşünmek yardımcı olabilir değişiklik notunu bir basın bülteni olarak duyurmak yerine Açıklama yap.

Örneğin, tarih işlemeden kaynaklanan bir hatayı düzeltirseniz, commit mesajı veya çekme isteği açıklaması okunabilir:

DateWidget doğrulamasına bir MM-DD-YYY format doğrulayıcısı eklendi Zincir.

Bu, uygulamada yapılan değişikliği açıklamaktadır - detay kodu gözden geçiren kişiye yardımcı olacaktır. Bununla birlikte ilgili değişiklik notu aşağıdaki gibi bir şey olabilir:

Tarih widget'ları artık ABD formatındaki tarihleri kabul edebilir.

Bu, son kullanıcılar tarafından deneyimleneceği şekliyle işlevsel değişikliği tanımlar. kullanıcılar. Bir kullanıcı hiçbir şey bilmesine gerek kalmadan bu açıklamayı okuyabilir uygulama hakkında.

Kod stili

BeeWare'in projeleri otomatikleştirmek için [Pre-commit] (https://pre-commit.com/) kullanır kod stiline bağlılık. Bu kontroller şu şekilde tanımlanır Her depo için .pre-commit-config.yaml dosyası ve otomatik olarak bir Çekme İsteği olduğunda CI içinde çalıştırılır açıldı.

Yerel geliştirme ortamınızda Pre-commit kontrollerini otomatikleştirmek için her git işlemiyle birlikte pre-commit install çalıştırın.

Ön taahhüt kontrolleri dahil:

  • Black sağlar tek tip kod biçimlendirmesi
  • docformatter sağlar doküman dizileri ve yorumlar için tek tip biçimlendirme
  • pyupgrade kodun şu şekilde olmasını sağlar Python için en son en iyi uygulamaları kullanma
  • isort tek tip ithalat sağlar ifadeler
  • flake8 ortak kodlama için kontroller ve sözdizimi sorunları
  • TOML dosyaları gibi yapılandırılmış belgeleri doğrulayan çeşitli kontroller ve Gereksiz boşlukları kaldırın

Ek yönergeler:

  • Yorumlarda "biz" kelimesini kullanmaktan kaçının, örneğin "Döngü yapıyoruz" yerine "Döngü bitti bitti"

  • Değişken, işlev ve yöntem için camelCase değil, alt çizgi kullanın isimler

  • Sınıf adları için InitialCaps kullanın (veya dönen fabrika işlevleri için sınıflar)

  • Sphinx tarzı dokümanlar ve 257 kullanın; 484 ile tür ek açıklaması isteğe bağlı ama teşvik edilir.

    Örneğin:

    def function_name(param1: int, param2: str) -> bool:
    """Tipleri ve docstring'i olan örnek fonksiyon.

    :param param1: İlk parametre.
    :param param2: İkinci parametre.

    :döner: Dönüş değeri. Başarı için True, aksi takdirde False.
    """

  • Test dokümanlarında, her testten beklenen davranışı belirtin gösterir. "Şunu test eder" veya "Şunu sağlar" gibi giriş cümlelerine yer vermeyin. o".

  • Biletin sahip olduğu belirsiz sorunlar için bilet referanslarını ayırın dokümanlarda kolayca açıklanamayan ek ayrıntılar veya Yorumlar. Bilet numarasını aşağıdaki gibi bir cümlenin sonuna ekleyin Bu:

    def test_foo():
    """Bir test doküman dizisi şuna benzer (#123456)."""

  • Aksi belirtilmedikçe, 8i takip edin (aşağıdakilere dikkat ederek) Bölüm 2).