Bu doküman, Bazel'deki katkıda bulunanları hedeflemektedir.
Bazel'deki kaydetme açıklamaları arasında bir RELNOTES: etiketi ve ardından bir sürüm notu bulunur. Bu bilgi, Bazel ekibi tarafından her sürümdeki değişiklikleri izlemek ve yayın duyurusunu yazmak için kullanılır.
Genel bakış
Yaptığınız değişiklik bir hata düzeltmesi mi? Bu durumda sürüm notuna ihtiyacınız yoktur. Lütfen GitHub sorunuyla ilgili bir referans ekleyin.
Değişiklik, Bazel'i kullanıcıların görebileceği şekilde ekler/kaldırır veya değiştirirse bu durumdan bahsetmek avantajlı olabilir.
Değişiklik önemliyse önce tasarım dokümanı politikasını uygulayın.
Kurallar
Sürüm notları kullanıcılarımız tarafından okunacağı için kısa (ideal olarak tek cümlelik) olmalı, jargondan (Bazel ve şirket içi terminoloji) kaçınılmalı, değişikliğin neyle ilgili olduğuna odaklanılmalıdır.
İlgili belgelerin bağlantısını ekleyin. Neredeyse her sürüm notunda bir bağlantı bulunmalıdır. Açıklamada bir işaret, özellik, komut adı belirtiliyorsa kullanıcılar muhtemelen daha fazla bilgi edinmek isteyecektir.
Kod, semboller, bayraklar veya alt çizgi içeren herhangi bir kelimenin başında geriye doğru tırnak işaretleri kullanın.
Hata açıklamalarını kopyalayıp yapıştırmakla yetinmeyin. Bunlar genellikle şifrelidir ve yalnızca bize anlamlı görünürler ve kullanıcının kafasını kaşıyırlar. Sürüm notları, nelerin neden değiştiğini kullanıcının anlayabileceği bir dille açıklamak için kullanılır.
Her zaman şimdiki zamanı ve "Bazel artık Y'yi destekliyor" veya "X artık Z'yi destekliyor" biçimini kullanın. Sürüm notlarımızın hata girişi gibi görünmesini istemeyiz. Tüm sürüm notu girişleri bilgilendirici olmalı, tutarlı bir stil ve dil kullanmalıdır.
Bir öğe kullanımdan kaldırıldıysa veya kaldırıldıysa "X desteği sonlandırıldı" veya "X kaldırıldı" ifadesini kullanın. "Kaldırıldı" veya "kaldırıldı" değil.
Bazel şimdi farklı bir şey yapıyorsa şimdiki zaman olarak "$oldBehavior yerine X artık $newBehavior"ı kullanın. Bu, kullanıcıların yeni sürümü kullanırken ne beklemeleri gerektiğini ayrıntılı olarak bilmelerine olanak tanır.
Bazel artık bir öğeyi destekliyor veya desteklemiyorsa "Bazel artık X'i destekliyor/artık desteklemiyor" ifadesini kullanın.
Bir şeyin neden kaldırıldığını / kullanımdan kaldırıldığını / değiştirildiğini açıklayın. Bir cümle yeterlidir, ancak kullanıcının derlemeleri üzerindeki etkiyi değerlendirebilmesini istiyoruz.
Gelecekteki işlevlerle ilgili hiçbir vaatte BULUNMAYIN. "Bu işaret kaldırılacak" veya "bu değiştirilecek" gibi ifadelerden kaçının. Belirsizliğe neden olur. Kullanıcının merak edeceği ilk şey "ne zaman?" olur ve şu anki derlemelerinin bilinmeyen bir zamanda bozulması konusunda endişelenmesini istemeyiz.
İşleme
Yayın sürecinin bir parçası olarak her kaydın RELNOTES etiketlerini toplarız. Bir Google Dokümanı'ndaki her şeyi kopyalarız.
Burada notları inceler, düzenler ve organize ederiz.
Sürüm yöneticisi, bazel-dev posta listesine bir e-posta gönderir. Bazel'e katkıda bulunanlar, dokümana katkıda bulunmaya davet edilir ve değişikliklerinin duyuruda doğru şekilde yansıtılmasını sağlar.
Daha sonra duyuru, bazel-blog deposu kullanılarak Bazel bloguna gönderilecektir.