Bu doküman, Bazel'e katkıda bulunan kullanıcıları hedefler.
Bazel'deki taahhüt açıklamaları, bir RELNOTES: etiketi ve ardından bir yayın notu içerir. Bu sürüm, Bazel ekibi tarafından her bir sürümdeki değişiklikleri izlemek ve sürüm 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 sorunu için bir referans ekleyin.
Değişiklik Bazel'ı kullanıcıların görebileceği şekilde ekliyor / kaldırıyorsa / değiştiriyorsa bundan bahsetmek avantajlı olabilir.
Değişiklik önemliyse ilk olarak tasarım belgesi politikasını uygulayın.
Yönergeler
Sürüm notları kullanıcılarımız tarafından okunacağı için kısa (ideal olarak bir cümle) olmalı, jargondan (Bazel-dahili terminoloji) kaçınılmalı ve 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 bağlantı bulunmalıdır. Açıklamada bir bayrak, özellik veya komut adından bahsediliyorsa kullanıcılar muhtemelen bu konuda daha fazla bilgi edinmek isteyecektir.
Kod, simge, işaret veya alt çizgi içeren tüm kelimelerin etrafında tırnak işaretleri kullanın.
Hata açıklamalarını kopyalayıp yapıştırmakla kalmayın. Çoğunlukla şifreli olan bu oyunlar sadece bizim için anlamlı ve kullanıcının aklını karıştırıyor. Sürüm notları, nelerin ve neden değiştiğini kullanıcıların anlayabileceği bir dille açıklar.
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şleri gibi görünmesini istemiyoruz. 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 kullanımdan kaldırıldıysa "X desteği sonlandırıldı" veya "X kaldırıldı" ifadelerini kullanın. "Kaldırıldı" veya "kaldırıldı" değil.
Bazel şimdi farklı bir şey yapıyorsa mevcut zamandaki "$oldBehavior yerine $newBehavior" yerine "X now $newBehavior" kullanın. Bu sayede kullanıcı yeni sürümü kullanırken neler beklemesi gerektiğini ayrıntılı olarak bilir.
Bazel artık bir özelliği destekliyorsa veya artık desteklemiyorsa "Bazel artık X'i destekliyor/artık desteklemiyor" ifadesini kullanın.
Bir öğenin 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 yapıları üzerindeki etkiyi değerlendirebilmesini istiyoruz.
Gelecekteki işlevlerle ilgili herhangi bir söz vermeyin. "Bu bayrak kaldırılacak" veya "bu değiştirilecek" ifadelerinden kaçının. Belirsizlikleri beraberinde getirir. Kullanıcının merak edeceği ilk şey "ne zaman?" olur ve mevcut derlemelerinin bilinmeyen bir zamanda bozulacağı konusunda endişelenmeye başlamasını istemeyiz.
İşleme
Yayınlama sürecinin bir parçası olarak, her kaydetmenin RELNOTES etiketlerini toplarız. Notları incelediğimiz, düzenlediğimiz ve düzenlediğimiz bir Google Dokümanında her şeyi kopyalarız.
Sürüm yöneticisi bazel-dev posta listesine bir e-posta gönderir. Bazel katkıda bulunanları dokümana katkıda bulunmaya ve değişikliklerinin duyuruya doğru şekilde yansıtıldığından emin olmaya davet edilir.
Daha sonra duyuru, bazel-blog deposu kullanılarak Bazel bloguna gönderilecektir.