Release notu şablonu

Şablon

Köşeli parantez içindeki her şey bir yer tutucudur. Geri kalan her şey, sıralama dahil, korunmaya değer: kullanıcılar kendilerini etkileyen şeyi tarar, bu yüzden kırıcı değişiklikler önce gelir ve dahili çalışma hiç görünmez.

## [Ürün] [sürüm] - [tarih]

[Bu sürümün ne için olduğunu anlatan bir cümle. Rutin sürümlerde atla.]

### Kırıcı değişiklikler
- [Ne bozuldu, yerine ne yapılmalı ve ne zamana kadar. Geçiş
  adımlarına bağlantı ver.]

### Yeni
- [Bir sonuç olarak tanımlanan yetenek. "Bir filtreyi sabitle ve
  yeniden kullan", "SavedView modeli eklendi" değil.]

### İyileştirildi
- [Ne daha hızlı, daha net veya daha güvenilir hale geldi, yaklaşık
  ne kadar.]

### Düzeltildi
- [Kullanıcının gördüğü belirti, koddaki sebep değil.]

Bir bölüm boşsa başlığı sil. Boş bir Düzeltildi bölümü sanki hiçbir şey düzeltilmemiş gibi okunur ve altında hiçbir şey olmayan bir başlık okuyuculara sayfanın yüklenemediğini düşündürür.

Aynı şablon, doldurulmuş hâli

Gerçek içerikle böyle görünür. Hiçbir kaydın bir dosyadan, bir daldan, bir bilet numarasından veya bir kişiden bahsetmediğine ve kırıcı değişikliğin okuyucunun yapması gereken eylemle başladığına dikkat et.

## Acme API 4.2 - 20 Ağustos 2026

Sayfalama artık tüm liste endpoint'lerinde cursor tabanlı.

### Kırıcı değişiklikler
- Tüm liste endpoint'lerinde `?page=` kaldırıldı. Önceki yanıttaki
  `nextCursor` değerini kullan. `?page=`, 1 Ekim 2026'dan sonra
  400 döndürür. Geçiş adımları: acme.example/docs/pagination

### Yeni
- Inbox'ta kayıtlı görünümler. Bir filtreyi bir kez sabitle ve
  kenar çubuğundan yeniden kullan.
- Webhook'lar artık tek bir projeyle sınırlandırılabilir.

### İyileştirildi
- Liste endpoint'leri büyük hesaplarda yaklaşık dört kat daha
  hızlı yanıt veriyor.
- Dışa aktarma işi askıda kalmış gibi görünmek yerine ilerlemeyi
  bildiriyor.

### Düzeltildi
- Davet edilen üyeler artık ilk girişlerine kadar boş bir kontrol
  paneline düşmüyor.
- Dışa aktarımlardaki zaman damgaları artık hesabın saat dilimine
  saygı gösteriyor.

Her bölüme ne girer

Kırıcı değişiklikler

İçinde bir son tarih olan tek bölüm. Neyin çalışmayı durdurduğunu, yerine ne yapılacağını ve durma tarihini söyle. Tarihe henüz karar vermediysen bölümü yayımlama: tarihsiz bir kırıcı değişiklik acil olarak okunur, ve sahte aciliyet akışı, insanların release notlarını görmezden gelmeyi öğrendiği yoldur.

Yeni

İnşa ettiğin nesneyi değil sonucu tanımla. Test şudur: satır, kod tabanını hiç görmemiş birine hâlâ anlam ifade ediyor mu. "Inbox'ta kayıtlı görünümler" geçer. "SavedView modeli ve geçişi eklendi" geçmez.

İyileştirildi

Dürüstçe yapabildiğin yerde sayısallaştır. "Daha hızlı" neredeyse hiçbir şey ifade etmez ve okuyucular bunu göz ardı eder; "büyük hesaplarda yaklaşık dört kat daha hızlı" okumaya değer ve seni sorumlu tutabilecekleri bir beklenti oluşturur. Ölçemiyorsan, neyin daha iyi olduğunu yanlışlanabilir bir şekilde söyle.

Düzeltildi

Sebebi değil belirtiyi yaz. Kullanıcılar bu notları başlarına gelen şeyi bulmak için arar, bu yüzden "davet edilen üyeler boş bir kontrol paneline düştü" bulunabilir ama "üyelik önbelleğindeki bir yarış durumu düzeltildi" değildir.

Varyantlar

Dört bölüm çoğu sürüm için geçerlidir. Üç durum bir değişiklik ister:

• Mobil uygulama sürümleri. Uygulama mağazaları kısa bir yenilikler alanı gösterir, bu yüzden mağaza listesinde bir kişinin okuyabileceği tek bir cümleyle başla, sonra tam notlara bağlantı ver. Mağaza incelemesi bir sürümü günlerce erteleyebilir, bu yüzden notları birleştirme tarihine değil sürüm tarihine göre tarihlendirmiş.
• API sürümleri. Notları API'yi sürümlediğin şekilde sürümle ve kullanımdan kaldırma penceresini yalnızca dokümanlarda değil notların kendisinde de belirt. Bir API tüketicisi notları tam olarak ne kadar süresi olduğunu öğrenmek için okur.
• Dahili veya yönetici araçları. İyileştirildi bölümünü bırak ve Düzeltildi ile birleştir. Dahili kullanıcılar iş akışlarının değişip değişmediğini önemser ve uzun bir İyileştirildi bölümü bunu gömer.

Bunları okunabilir tutan dört kural

1. Kod tabanını bilmeyen biri için yaz. Dosya adı yok, dal adı yok, bilet kimliği yok, servis adı yok, dahili kod adı yok.
2. Kullanıcıya görünür bir etkisi olmayan her şeyi çıkar. Bağımlılık güncellemeleri, refactor'lar, CI değişiklikleri ve yazım düzeltmeleri commit geçmişine aittir, release notlarına değil. Release notlarının en yaygın ölüş şekli, ekip dışında kimsenin göremediği işle dolup taşmasıdır.
3. Bir kayıt, bir değişiklik. Bir satır "ve" kelimesine iki kez ihtiyaç duyuyorsa muhtemelen iki kayıttır.
4. İnsanların güvenebileceği bir ritimde yayımla, ritim "ne zaman gönderirsek" olsa bile. Bir haftada dört kez görünüp sonra iki ay görünmeyen notlar gürültü olarak değerlendirilir.

Release notu formatı: parçalar, sırasıyla

Format, sıradan daha az önemlidir. Hangi başlık stilini kullanırsan kullan, release notlarını tarayan bir okuyucu aynı dört şeyi aynı sırayla ister ve popüler her release notu formatı bunun bir varyasyonudur.

1. Sürüm numarasını değil, okuyucu için neyin değiştiğini söyleyen bir başlık. Sürüm, her yerelde aynı şekilde okunması için ISO biçiminde (2026-08-29) tarihle birlikte altında daha küçük bir satırda gider.
2. Kırıcı değişiklikler ve bir son tarihi olan her şey, küçük olsa bile önce. Bir okuyucu bir paragraftan sonra durursa, ihtiyacı olan paragraf budur.
3. Yeni olan, paragraf başına bir öğe, ilk cümlede sonuçla ve her seferinde belirtilen, "eylem gerekmiyor" dahil, gereken eylemle.
4. Düzeltmeler ve iyileştirmeler, sonra alt kısımda tek satırlık bir liste olarak geri kalan her şey. Bağımlılık güncellemeleri ve dahili değişiklikler kalır, çünkü onları arayan tek kişi gerçekten onlara ihtiyaç duyar.

Markdown'da bu bir H2 başlık, soluk bir sürüm ve tarih satırı, sonra Kırıcı, Yeni, İyileştirildi ve Düzeltildi için H3 bölümleridir. Bir e-postada aynı sıra, konu olarak başlıkla birlikte gelir. Bir changelog widget'ında başlık ve ilk paragraftır, geri kalanı bir bağlantının arkasındadır. Yukarıdaki şablon bu şeklin yazıya dökülmüş hâlidir.

Şeklin kendisi yerine yazımın kendisi için blogda insanların gerçekten okuduğu release notları nasıl yazılır ve saklamaya değer release notu en iyi uygulamalarına bak.

Sık sorulan sorular

Release notları ne kadar uzun olmalı?

Kullanıcıları etkileyen değişiklikler kadar, ne fazla ne az. Tek bir hata düzeltmesi olan bir sürüm iki satır alır. Küçük bir sürümü önemli görünmesi için doldurmak, insanlara büyük olanları hızlıca geçmeyi öğretir.

Release notları ile changelog arasındaki fark nedir?

Pratikte terimler birbirinin yerine kullanılır. Ekiplerin bunları ayırdığı yerlerde, release notları tek bir sürümü tanımlar ve kullanıcılar için yazılır, changelog ise zaman içindeki her sürümün süregelen listesidir. Bu şablon tek bir sürümü kapsar; bir changelog, bunları en yeniden en eskiye istifleyince elde ettiğin şeydir.

Release notlarında sürüm numarası olmalı mı?

Yalnızca kullanıcıların onu görebiliyorsa. Sürüm numaraları, bir okuyucunun hangi sürümde olduğunu bilmesi gereken API'ler, kütüphaneler ve kurulu yazılımlar için kullanışlıdır. Sürekli dağıtılan bir web uygulaması için tarih daha kullanışlıdır, çünkü kullanıcının deneyimiyle karşılaştırabileceği şey odur.

Bunları kim yazmalı?

Neyin değiştiğini bilen kişi, ki bu genellikle onu birleştiren mühendistir, sesin sahibi olan kişi tarafından düzenlenir. Bunları tamamen işin dışındaki birine bırakmanın başarısızlık modu, değişikliği değil bileti tanımlayan notlardır.