Release notlari disiplini

Kullanıcılar yeni sürümü indirdiğinde ilk bakacakları yer release notes'tur. Geliştirici ekipleri içinde ise sürüm notları, operasyon, destek ve ürün yönetimi arasındaki ortak dil haline gelir. Disiplinsiz sürüm notları "bug fixler ve iyileştirmeler" cümlesiyle geçiştirildiğinde, değişikliklerin etkisi görünmez kalır ve geri dönüş kararları gecikir.

Sürüm notlarının amacı

Release notes üç farklı kitleye hitap eder:

• Son kullanıcılar: Yeni özellikler ve düzeltilen sorunlar
• Operasyon ekibi: Altyapı değişiklikleri, migration adımları, bilinen sorunlar
• API tüketicileri: Breaking change'ler, deprecation uyarıları, versiyon geçiş rehberi

Tek bir metin tüm kitleleri karşılayamaz. İyi uygulamada kullanıcıya yönelik özet ile teknik detay ayrılır veya etiketlerle bölümlendirilir.

Keep a Changelog formatı

Keep a Changelog standardı, sürüm notları için yaygın kabul görmüş bir yapı sunar. Her sürüm şu kategorilere ayrılır:

• Added: Yeni özellikler
• Changed: Mevcut işlevde değişiklikler
• Deprecated: Yakında kaldırılacak özellikler
• Removed: Kaldırılan özellikler
• Fixed: Hata düzeltmeleri
• Security: Güvenlik yamaları

Örnek giriş:

## [2.4.0] - 2026-07-20

### Added
- Sipariş geçmişinde CSV dışa aktarma

### Fixed
- Çift tıklamada yinelenen ödeme kaydı (#1847)

### Security
- JWT imza algoritması HS256'dan RS256'ya güncellendi

Semantic Versioning ile uyum

Sürüm numaraları SemVer (MAJOR.MINOR.PATCH) kurallarına uymalıdır:

1. MAJOR: Geriye dönük uyumsuz API değişikliği
2. MINOR: Geriye dönük uyumlu yeni özellik
3. PATCH: Geriye dönük uyumlu hata düzeltmesi

Release notes'taki breaking change bölümü MAJOR sürümle eşleşmelidir. Kullanıcı MAJOR sürüm görünce dikkatli okuma yapar; bu beklenti bozulmamalıdır.

Conventional Commits

Otomatik changelog üretiminin temeli, standartlaştırılmış commit mesajlarıdır:

feat(orders): add CSV export for order history
fix(payment): prevent duplicate charge on double-click
BREAKING CHANGE: auth tokens now use RS256 signing

Commit tipleri changelog kategorilerine eşlenir:

• feat → Added
• fix → Fixed
• perf → Changed (performans)
• BREAKING CHANGE footer → breaking change uyarısı

Otomasyon araçları

Manuel changelog güncellemesi unutulmaya açıktır. Otomasyon seçenekleri:

• standard-version: Node.js projelerinde semver bump + CHANGELOG.md güncelleme
• release-please: Google'ın GitHub Action'ı; PR bazlı release
• semantic-release: Tam otomatik sürüm ve yayın
• git-cliff: Rust tabanlı, hızlı changelog generator

CI pipeline'ında release tag oluşturulduğunda changelog otomatik üretilir ve GitHub Release'e eklenir.

İyi sürüm notu yazma kuralları

Teknik olarak doğru ama kullanıcıya anlamsız notlardan kaçının:

• "Refactor OrderService" yerine "Sipariş listesi yükleme hızı iyileştirildi"
• Issue veya PR numarası referans verin (#1847)
• Breaking change'lerde migration adımlarını açık yazın
• Bilinen sorunları gizlemeyin; güven oluşturur

Her madde tek bir değişikliği anlatmalıdır. "Çeşitli bug fixler" gibi toplu ifadeler değer taşımaz.

Internal vs external notes

Kurumsal ürünlerde iki katmanlı release notes yaygındır:

1. Public changelog: Müşteriye açık, pazarlama dili ile yazılmış
2. Internal release notes: Veritabanı migration scriptleri, feature flag durumları, rollback prosedürü

Internal notes operasyon ekibinin deployment checklist'inin parçası olmalıdır. "Bu sürümde X tablosuna Y kolonu eklenir; migration otomatik çalışır" gibi somut bilgiler içermelidir.

Release notes ve deployment

CD pipeline'ında release notes deployment kapısının parçası olabilir:

• CHANGELOG.md güncellenmeden tag oluşturulamaz
• Breaking change varsa otomatik olarak ek onay gerektirir
• Release notes Slack veya Teams kanalına otomatik gönderilir

Destek ekibi yeni sürümde hangi sorunların çözüldüğünü bilir; müşteri ticket'larına daha hızlı yanıt verir.

API sürüm notları

Public API sunan servislerde release notes ayrı bir doküman olarak tutulmalıdır. Deprecation politikası açık olmalı:

## Deprecation Notice
- GET /v1/users/{id}/profile → v2'de kaldırılacak (2026-12-01)
- Yerine GET /v2/users/{id} kullanın

API changelog, OpenAPI spec değişiklikleriyle birlikte versiyonlanır. Consumer'lar breaking change'i önceden görür ve geçiş planlar.

Metrikler ve geri bildirim

Release notes kalitesini ölçmek zor ama şu sinyaller faydalıdır:

• Sürüm sonrası "ne değişti?" destek ticket sayısı
• Breaking change sonrası API hata oranı artışı
• Rollback sıklığı ve gerekçeleri

Rollback gerekçeleri release notes sürecine geri beslenmelidir; eksik bilgi bir sonraki sürümde tamamlanır.

Takım disiplini

Release notes disiplini yalnızca release manager'ın sorumluluğu değildir. Her geliştirici, pull request açarken changelog etkisini düşünmelidir. PR template'ine şu sorular eklenebilir:

1. Bu değişiklik kullanıcıya görünür mü?
2. Breaking change var mı?
3. Migration veya manuel adım gerekiyor mu?

Code review sırasında commit mesajı formatı da kontrol edilir. Conventional commit disiplini, otomatik changelog'un güvenilirliğini belirler.

Özet

Çoklu ürün ve monorepo senaryoları

Monorepo yapısında birden fazla paket veya servis aynı repoda yaşar. Her paketin kendi CHANGELOG.md dosyası olmalıdır; root changelog yalnızca koordinasyon sürümünü özetler. Lerna, Changesets veya Nx release mekanizması bağımsız paket sürümlemesini yönetir. Bir paketteki breaking change, diğer paketlerin sürümünü etkilememelidir.

Changesets workflow'unda geliştirici PR'a bir changeset dosyası ekler; merge sonrası "Version Packages" PR'ı otomatik açılır. Bu PR changelog güncellemesi ve sürüm bump içerir; onay sonrası publish tetiklenir.

Regülasyon ve denetim gereksinimleri

Finans ve sağlık sektörlerinde sürüm notları denetim izinin parçasıdır. Her release'te değişen bileşenler, güvenlik yamaları ve bilinen açıklar dokümante edilmelidir. SBOM (Software Bill of Materials) çıktısı release artifact'ına eklenir. Denetçi, belirli bir sürümde hangi bağımlılıkların bulunduğunu sürüm notları ve SBOM ile doğrular.

Müşteri iletişim kanalları

Release notes yalnızca GitHub Release sayfasında kalmamalıdır. E-posta bülteni, uygulama içi "yenilikler" ekranı ve dokümantasyon sitesindeki changelog sayfası senkron tutulmalıdır. Otomasyon pipeline'ı aynı markdown kaynağından farklı formatlara (HTML e-posta, JSON API feed) dönüşüm yapabilir.

Major sürümlerde migration guide ayrı bir doküman olarak yayınlanır. Release notes'ta kısa özet ve migration guide linki verilir; uzun teknik adımlar ayrı sayfada detaylandırılır.

Changelog kalite kontrolü

Release öncesi checklist:

1. Her kategori en az bir madde içeriyor mu veya bilinçli olarak boş mu?
2. Breaking change'ler vurgulanmış mı?
3. Issue/PR referansları çözülmüş mü?
4. Operasyon ekibi internal notes aldı mı?
5. Deprecation tarihleri net mi?

Changelog review, code review kadar formal olmalıdır. Release manager son onayı verir; eksik veya belirsiz madde release'i geciktirir.

Sürüm notları ve güvenlik açıkları

Güvenlik yamaları release notes'ta açık ve zamanında belirtilmelidir. CVE numarası, etkilenen sürüm aralığı ve yükseltme zorunluluğu net yazılır. Güvenlik açığını gizlemek veya "genel iyileştirmeler" altında saklamak, kullanıcıların savunmasız sürümde kalmasına neden olur. Responsible disclosure takvimine uygun olarak public changelog güncellenir.

Kritik güvenlik sürümü (hotfix) için abbreviated release notes kabul edilebilir; ancak en azından "Security: CVE-2026-XXXX giderildi, acil yükseltme önerilir" ifadesi zorunludur.

Uluslararası ekipler için dil stratejisi

Global ürünlerde release notes İngilizce master, Türkçe ve diğer diller çeviri olarak yönetilir. Çeviri otomasyonu (i18n pipeline) changelog commit'ine bağlanır. Teknik terimler (breaking change, deprecation) tutarlı çeviri sözlüğünde tanımlıdır; her çevirmen farklı terim kullanmaz.

Release notes, yazılım teslimatının görünür yüzüdür. Keep a Changelog yapısı, SemVer kuralları ve Conventional Commits ile otomasyon kurulduğunda, sürüm notları hem kullanıcıya değer sunar hem de operasyonel güvenilirliği artırır. Disiplinli sürüm notları kültürü, olgun bir DevOps organizasyonunun göstergelerinden biridir.