Sürüm notları için değişiklik bilgileri ekleme

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.