Yazılım release notes: nedir ve neleri içermelidir

Yazılım release notes, bir yazılım sürümüne eşlik eden ve okuyucuya içinde neyin değiştiğini, değişikliğin kimi etkilediğini ve varsa ne yapması gerektiğini söyleyen belgedir. Her release için bir kez yazılır; yükseltip yükseltmeyeceğine karar verenler, karşılaştıkları sorunun düzelip düzelmediğine bakanlar ve ürünü destekleyenler okur. İyileri kısa, sürüme özgü ve bozulan her şey konusunda dürüsttür.

Yazılım release notes nedir?

Tek bir release’in tarihli, sürümlü özetidir. Bir release note, odada olmayan okuyucu için üç soruyu cevaplar: ne farklı, beni etkiliyor mu ve harekete geçmem gerekiyor mu. Projenin tüm geçmişi changelog’dur, commit logu ise kodu yazanlar içindir.

Aynı olgular hem bir changelog girdisinde hem de release notes’ta yer alabilir. Fark seçim ve hedef kitlededir: changelog kayda değer her değişikliği listeler, release notes ise okuyucunun fark edeceği olanlarla açılır ve onları açıklar. Changelog vs release notes yazısı çizgiyi ayrıntılı çeker.

Yazılım release notes neleri içermelidir?

Sürümü ve tarihi, tek paragraflık bir özeti ve ardından değişiklikleri okuyucunun onlarla ne yapabileceğine göre gruplanmış olarak yazın. Her değişiklik için okuyucunun diliyle neyin farklı olduğunu, kimin etkilendiğini ve bir eylem gerekip gerekmediğini söyleyin.

Eksiksiz bir set şu parçalardan oluşur:

1. Sürüm numarası ve release tarihi. Etiketlerinizin kullandığı biçimi kullanın, böylece okuyucu notları bir build ile eşleştirebilir.
2. Bir özet. İki üç cümle: bu release ne için ve yükseltmek okuyucudan bir şey istiyor mu.
3. Yeni özellikler ve iyileştirmeler. Okuyucunun artık ne yapabildiği, kodun artık neyi içerdiği değil.
4. Düzeltmeler. Ortadan kalkan belirti ve başladığı sürüm.
5. Breaking change’ler ve deprecation’lar. Neyin çalışmayı bıraktığı, ne zaman ve onun yerine neyin kullanılacağı. Varsa bunları en başa koyun.
6. Bilinen sorunlar. Doğru olmadığını bildiğiniz her şey, varsa geçici çözümüyle.
7. Gereksinimler ve yükseltme adımları. Desteklenen platformlar, minimum sürümler, geçiş komutları.

Refactor’ları, görünür etkisi olmayan bağımlılık güncellemelerini ve dahili ticket’ları dışarıda bırakın. Okuyucu değişikliği fark edemiyorsa yeri git geçmişidir. Release notes nasıl yazılır yazısı ifade ve sırayı ele alır.

Bir yazılım release note’u nasıl görünür?

Uydurma bir komut satırı aracı için kısa bir örnek. İçerikten çok şekil önemli.

## 2.4.0 (2026-10-08)

Faster exports and one breaking change to the config file. Upgrade
needs a one-line edit to `tool.yml`.

### Breaking
- `output:` in `tool.yml` is now `export.path:`. Old configs fail
  with "unknown key". Rename the key; nothing else changes.

### New
- Exports stream to disk, so files over 100 MB no longer time out.

### Fixed
- Search works again for queries containing a hyphen. Broken
  since 2.3.0.

### Known issues
- Windows paths longer than 260 characters still fail. Use a
  shorter output directory for now.

Breaking change en başta ve okuyucunun göreceği tam hata metniyle duruyor, çünkü insanlar hata mesajlarını arar. Düzeltme, bozulduğu sürümü adlandırıyor; böylece okuyucu bunu kendi sorununun başladığı zamanla eşleştirebilir. Bilinen sorunun bir geçici çözümü var, ki bu sessiz kalmaktan iyidir. Release notes örnekleri yazısında her girdi türü için daha fazla ifade var.

Yazılım release notes her hedef kitle için nasıl farklılaşır?

Tek bir doğruluk kaynağı tutun ve her hedef kitle için bir sürüm yazın. Olgular değişmez, ama ayrıntı düzeyi değişir. Müşteriler faydayı tek satırda ister, yöneticiler gereksinimleri ve bilinen sorunları, geliştiriciler tam adları ve sürümleri, destek ise bir ticket geldiğinde ne diyeceğini bilmek ister.

API ürünlerinde geliştirici sürümü en çok özen ister, çünkü sizin için küçük bir düzeltme olan şey çağıran için bir kesinti olabilir. API changelog ve breaking change’ler yazıları bu kitleyi ele alır. Dahili sürüm için dahili release notları yazısı, destek ve satışın müşterilerin ihtiyaç duymadığı hangi şeylere ihtiyaç duyduğunu anlatır.

Yazılım release notes nerede yayımlanmalı?

Okuyucunun soruyu sorduğu anda zaten bulunduğu yerde yayımlayın. Bir mobil uygulama için bu, platformun her sürüm için bir release notes alanı sunduğu mağaza sayfasıdır; Apple, build’ler için release notes’un nasıl sağlanacağını belgeliyor. Bir web ürünü için uygulamadan bağlanan bir changelog sayfasıdır. Bir kütüphane için release sayfası ve depodaki bir dosyadır; bu, GitHub release notes yazısında anlatılıyor.

Her sürümü sabit bir URL’de tutun ki destek ona link verebilsin, ve eski sürümleri saklayın. 2.2 sürümündeki bir okuyucunun 2.3 ve 2.4 notlarına da ihtiyacı var. Başlangıç yapısı isterseniz release notes şablonu kopyalayabileceğiniz başlıkları verir.

Release notes ne kadar uzun olmalı?

Değişikliğin ihtiyaç duyduğu kadar, daha fazla değil. Bir patch release üç satır olabilir. Geçiş gerektiren bir major release bir sayfa ister ve büyük olasılıkla notlardan bağlanan ayrı bir geçiş kılavuzu. Ölçüt, ilk ekrana göz gezdiren bir okuyucunun release’in kendisini etkileyip etkilemediğini anlayıp anlamadığıdır. Anlamıyorsa özeti yukarı taşıyın ve gerisini kesin. Release notes en iyi uygulamaları yazısı nelerin işe yaradığını ve nelerin alışkanlık olduğunu listeler.

FAQ

Yazılım release notes nedir? Bir yazılımın tek bir release’inde neyin değiştiğinin, onu kullanan veya destekleyen insanlar için yazılmış sürümlü özetidir. Yeni özellikleri, düzeltmeleri, breaking change’leri ve okuyucunun yapması gereken her şeyi kapsar.

Release notes ile changelog arasındaki fark nedir? Changelog, kayda değer değişikliklerin eksiksiz ve sürekli kaydıdır. Release notes ise tek bir release hakkında, yükseltip yükseltmeyeceğine karar veren okuyucular için seçilmiş ve yeniden yazılmış bir mesajdır. Birçok ekip bir sürümün changelog girdisini onun release notes’u olarak yayımlar.

Yazılım release notes’u kim yazar? Genellikle ürün yöneticisi, bir teknik yazar veya değişikliği yayımlayan mühendis yazar, ton için de biri gözden geçirir. En iyi sonuç, değişikliğe en yakın kişi taslağı yazıp ikinci bir kişi okuyucu için düzenlediğinde çıkar.

Minör release’lerin release notes’a ihtiyacı var mı? Evet, kısa olanlar. Bir patch release bile neyin düzeltildiğini ve okuyucunun harekete geçmesi gerekip gerekmediğini söylemeli. Tek satırlık bir not hiç olmamasından iyidir, çünkü “hata düzeltmeleri ve iyileştirmeler” okuyucuya hiçbir şey söylemez.

Bu yazıdaki teknik iddialar bağımsız olarak kontrol edilmedi. Yanlış bir şey varsa bize söyle, düzeltelim.

changeloop'ta ilgili sayfalar: Release notu şablonu, Changelog örnekleri