Bu doküman Bazel katkıda bulunanları hedeflemektedir.
Bazel'daki taahhüt açıklamalarına RELNOTES: etiketi ve ardından bir sürüm notu dahildir. Bazel ekibi bu bilgileri, her sürümdeki değişiklikleri izlemek ve sürüm duyurusunu yazmak için kullanı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ı tarafından görülebilecek bir şekilde ekliyor, kaldırıyorsa/değiştiriyorsa bu durumdan bahsetmek avantaj sağlayabilir.
Değişiklik önemliyse önce 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 (tercihen bir cümle) olmalı, jargondan (Bazel dahili terminolojiden) kaçının neyle ilgili olduğuna odaklanmalıdır.
İlgili dokümanların bağlantısını ekleyin. Neredeyse tüm sürüm notları bağlantı içermelidir. Açıklamada bir işaret, özellik, komut adı geçiyorsa kullanıcılar muhtemelen bunun hakkında daha fazla bilgi edinmek isterler.
Kod, semboller, işaretler veya alt çizgi içeren kelimelerde çift tırnak işareti kullanın.
Hata açıklamalarını kopyalayıp yapıştırmayın. Bu tür içerikler genellikle kriptografiktir, bizim için anlam ifade eder ve kullanıcının aklını karıştırır. Sürüm notları, neyin değiştiğini ve bunların nedenini kullanıcının anlayabileceği bir dilde açıklamak içindir.
Her zaman geçerli 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 ve tutarlı bir stil ve dil kullanmalıdır.
Bir ürün kullanımdan kaldırıldıysa veya kaldırıldıysa "X kullanımdan kaldırıldı" ifadesini 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 için "$oldDavranış yerine X yeni davranış" ifadesini kullanın. Bu, kullanıcıya yeni sürümü kullanırken ne beklemesi gerektiğini ayrıntılı olarak bildirir.
Bazel artık bir şeyi destekliyorsa veya artık desteklemiyorsa "Bazel artık X'i destekliyor/desteklenmiyor"u 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 yeterli. Ancak kullanıcının derlemeleri üzerindeki etkiyi değerlendirebilmesini istiyoruz.
Gelecekteki işlevler için vaatte bulunmayın. "Bu işaret kaldırılacak" veya "bu değiştirilecek" şeklinden kaçının. Belirsizliği beraberinde getiriyor. Kullanıcının ilk olarak "ne zaman?" sorusunu yanıtlaması gerekir. Şu anda mevcut yapılarının bilinmeyen bir zamanda bozulacağı konusunda endişelenmelerini istemiyoruz.
İşleme
Yayın 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 katılımcıları, dokümana katkıda bulunmaya ve değişikliklerinin duyuruya doğru şekilde yansıtılmasına davet ediliyor.
Daha sonra, duyuru bazel-blog deposu kullanılarak Bazel bloguna gönderilir.