Bu doküman, Bazel'e katkıda bulunanlara yöneliktir.
Bazel'deki commit açıklamaları, yayın notuyla birlikte RELNOTES: etiketini içerir. Bu, Bazel ekibi tarafından her sürümdeki değişiklikleri izlemek ve sürüm duyurusunu yazmak için kullanılır.
Genel Bakış
Değişikliğiniz bir hata düzeltmesi mi? Bu durumda sürüm notuna ihtiyacınız yoktur. Lütfen GitHub sorununa referans ekleyin.
Değişiklik, Bazel'i kullanıcıların görebileceği şekilde ekliyor, kaldırıyor veya değiştiriyorsa bu değişikliği belirtmek faydalı olabilir.
Değişiklik önemliyse önce tasarım belgesi politikasına uyun.
Yönergeler
Sürüm notları kullanıcılarımız tarafından okunacağından kısa olmalı (ideal olarak tek bir cümle), jargon (Bazel'e özgü terminoloji) içermemeli ve değişikliğin neyle ilgili olduğuna odaklanmalıdır.
İlgili belgelerin bağlantısını ekleyin. Neredeyse tüm sürüm notlarında bir bağlantı olmalıdır. Açıklamada bir işaret, özellik veya komut adı geçiyorsa kullanıcılar büyük olasılıkla bu konuda daha fazla bilgi edinmek isteyecektir.
Kod, sembol, işaret veya alt çizgi içeren kelimelerin etrafında ters tırnak işareti kullanın.
Hata açıklamalarını kopyalayıp yapıştırmayın. Bunlar genellikle anlaşılması zor olur ve yalnızca bizim için anlam ifade eder. Kullanıcılar ise ne anlama geldiğini anlamaz. Sürüm notları, kullanıcının anlayabileceği bir dilde nelerin ve neden değiştiğini açıklamayı amaçlar.
Her zaman geniş 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şleri gibi görünmesini istemiyoruz. Tüm sürüm notu girişleri bilgilendirici olmalı, tutarlı bir stil ve dil kullanılmalıdır.
Bir özellik desteği sonlandırıldıysa veya kaldırıldıysa "X desteği sonlandırıldı" veya "X kaldırıldı" ifadelerini kullanın. "Kaldırıldı" veya "kaldırılmıştı" değil.
Bazel artık farklı bir şekilde çalışıyorsa "X artık $oldBehavior yerine $newBehavior" ifadesini şimdiki zamanda kullanın. Bu sayede kullanıcı, yeni sürümü kullandığında ne gibi değişikliklerle karşılaşacağını ayrıntılı olarak öğrenebilir.
Bazel'in artık desteklediği veya desteklemediği bir özellik varsa "Bazel artık X'i destekliyor/desteklemiyor" ifadesini kullanın.
Bir şeyin neden kaldırıldığını / kullanımdan kaldırıldığını / değiştirildiğini açıklama Bir cümle yeterli ancak kullanıcının derlemeleri üzerindeki etkiyi değerlendirebilmesini istiyoruz.
Gelecekteki işlevler hakkında SÖZ VERMEYİN. "Bu işaret kaldırılacak" veya "Bu değiştirilecek" gibi ifadelerden kaçının. Belirsizliğe yol açar. Kullanıcının ilk merak edeceği şey "ne zaman?" olacaktır ve mevcut derlemelerinin bilinmeyen bir zamanda bozulması konusunda endişelenmesini istemeyiz.
İşleme
Yayınlama süreci kapsamında, her commit'in RELNOTES etiketlerini toplarız. Notları incelediğimiz, düzenlediğimiz ve organize ettiğimiz bir Google Dokümanı'na
her şeyi kopyalıyoruz.
Yayın yöneticisi, bazel-dev posta listesine e-posta gönderir. Bazel'e katkıda bulunanlar, dokümana katkıda bulunmaya ve değişikliklerinin duyuruda doğru şekilde yansıtıldığından emin olmaya davet edilir.
Duyuru daha sonra bazel-blog repository kullanılarak Bazel bloguna gönderilir.