Sürüm notları yazma

Sorun bildir Kaynağı göster Gece · 7,3 · 7,2 · 7,1 · 7,0 · 6,5

Bu doküman, Bazel'deki katkıda bulunanları hedeflemektedir.

Bazel'deki kaydetme açıklamaları arasında RELNOTES: etiketi ve ardından bir sürüm bulunur not. Bu, Bazel ekibi tarafından her sürümdeki değişiklikleri izlemek ve sürümdeki değişiklikleri izlemek için kullanılır. yayın duyurusu yapmaktı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 sorununa bir referans ekleyin.

  • Değişiklik, Bazel'i kullanıcıların görebileceği şekilde ekler / kaldırır / değiştirirse bundan bahsetmek yararlı olabilir.

Değişiklik önemliyse tasarım dokümanındaki talimatları uygulayın politikasına öncelik verin.

Yönergeler

Sürüm notları kullanıcılarımız tarafından okunacağı için kısa olmalıdır (ideal olarak bir cümlecik), jargondan (Bazel-iç terminolojisi) kaçının), pek de önemli olmadığını düşünüyorum.

  • İlgili belgelerin bağlantısını ekleyin. Neredeyse her sürüm notu bir bağlantı içerir. Açıklamada bir bayrak, özellik, komut adı kullanıcıları muhtemelen daha fazla bilgi edinmek isteyecektir.

  • Kod, simge, bayraklar veya alt çizgi.

  • Hata açıklamalarını kopyalayıp yapıştırmakla yetinmeyin. Çoğunlukla şifreli ve yalnızca bir anlam ifade etmeli ve kullanıcıyı başını kaşımalıdır. Sürüm notları kullanıcının anlayabileceği bir dille açıklamak anlamına gelir.

  • Her zaman şimdiki zamanı ve "Bazel artık Y'yi destekliyor" biçimini kullanın. veya "X artık yapıyor " Sürüm notlarımızın hata girişi gibi görünmesini istemeyiz. Tüm sürümler girişlerin bilgilendirici olması, tutarlı bir stil ve dil kullanması gerektiğini unutmayın.

  • Bir öğe kullanımdan kaldırıldıysa veya kaldırıldıysa "X desteği sonlandırıldı" ifadesini kullanın veya "X kaldırıldı." "kaldırıldı" değil veya "kaldırıldı".

  • Bazel artık farklı bir işlem yapıyorsa "X now $newBehavior yerine $oldBehavior" şimdiki zaman. Bu, kullanıcının ne yapması gerektiğini beklentilerini karşılayabilir.

  • Bazel artık bir öğeyi destekliyor veya desteklemiyorsa "Bazel artık şunları destekliyor: / artık X'i desteklemiyor".

  • Bir şeyin neden kaldırıldığını / kullanımdan kaldırıldığını / değiştirildiğini açıklayın. Bir cümle ancak kullanıcıların derlemeleri üzerindeki etkiyi değerlendirebilmesini istiyoruz.

  • Gelecekteki işlevlerle ilgili hiçbir vaatte BULUNMAYIN. "Bu işaret kaldırıldı" veya "bu değişecek." Belirsizliğe neden olur. İlk olarak, kullanıcı "ne zaman?" diye soracaktır. artık bu kadar para kazanıp mevcut derlemelerinin bilinmeyen bir zamanda bozulduğunu gösterir.

İşleme

Bu sürüm kapsamında işlem, her kaydın RELNOTES etiketlerini toplarız. Google'daki her şeyi Belge ve organize ediyoruz.

Sürüm yöneticisi, bazel-dev posta listesi. Bazel katılımcılarını dokümana katkıda bulunmaya davet ediyoruz. değişiklikleri duyuruda doğru şekilde yansıtıldığından emin olun.

Daha sonra duyuru Bazel'e gönderilecektir. blog'u kullanarak bazel-blog depo.