Semantic versioning ve changelog'unuz

Semantic versioning, çağıran tarafa bir sürümün tek bir changelog girişi okumadan önce ne kadar canını yakabileceğini söyler. 2.4.1’den 2.5.0’a geçmek şunu söyler: yeni yetenek, hiçbir şey bozulmaz. 2.5.0’dan 3.0.0’a geçmek şunu söyler: güncellemeden önce bu girişi oku. Changelog ve sürüm numarası, aynı şeyi iki biçimde iddia etmesi gereken şeylerdir, ve ikisi arasındaki sürtünmenin çoğu tam olarak uyuşmadıklarında ortaya çıkar, ki bu spesifikasyonun ima ettiğinden daha sık olur.

Bir versiyondaki her sayı gerçekte ne vaat eder?

Semantic versioning, her biri neyi tetiklediğine dair katı bir kurala sahip üç sayı tanımlar: MAJOR.MINOR.PATCH. Bir MAJOR sıçraması, uyumsuz bir değişiklik anlamına gelir: doğru, mevcut bir entegrasyonun fark edebileceği ve bu yüzden değişmesi gereken bir şey. Bir MINOR sıçraması, geriye dönük uyumlu yeni işlevsellik anlamına gelir: mevcut hiçbir şey bozulmaz, yeni bir şey kullanılabilir olur. Bir PATCH sıçraması, geriye dönük uyumlu bir düzeltme anlamına gelir: davranış belgelenmiş olana daha yakınlaşır, ve eski davranışa kasıtlı olarak güvenen hiç kimse hiçbir şey fark etmemelidir.

Tablo, geriye doğru da bir testtir: bir giriş kendi satırı gibi okunmuyorsa, ya sürüm numarası yanlıştır ya da giriş gerçekte ne olduğunu az veya çok satmaktadır.

Sürümleme amaçları için ne uyumsuz sayılır?

Bir şeyin API changelog’una ait olup olmadığına karar veren aynı test: eski davranışa karşı yazılmış ve o zamandan beri dokunulmamış doğru bir çağıran, bu değişiklik yüzünden farklı davranabilir mi. Uyumsuz bir değişiklik nedir, ve nasıl gönderilir kararı baştan sona ele alır, uyumsuz görünüp öyle olmayan ve küçük görünüp öyle olmayan durumlar dahil. Sürümleme için kısacası: yanıt evetse, değişikliğin dahili olarak gerçekte ne kadar kod etkilediğine bakılmaksızın sıçrama MAJOR’dır. Sürüm numaraları, ekibin çabasını değil, çağıran için sonucu takip eder.

Bir changelog girişi bir sürüm sıçramasına nasıl uymalı?

Bir giriş, bir sıçrama kategorisi, en baştan belirtilmiş. Tablodaki desen doğrudan devam eder: uyumsuz bir giriş, onu tanıtan sürümün altında yer alır, önce uyarı sonra açıklama olarak ifade edilir. Ek bir giriş, MINOR sürümünün altında yer alır, kullanılabilirlik olarak ifade edilir. Bir düzeltme, PATCH sürümünün altında yer alır, düzeltme olarak ifade edilir. Kategorileri bir girişte karıştırmak, örneğin uyumsuz bir değişikliği ilgisiz bir düzeltmeyle aynı paragrafa katlamak, bir okuyucunun gerçekten önemli olan tek şeyi tam olarak kaçırmasının yoludur.

## 3.0.0 (2026-09-07)

### Changed
- **BREAKING:** `GET /reports` artık tutarları ondalık yerine en küçük
  para birimi cinsinden (kuruş) tam sayı olarak döndürüyor. `amount`'ı
  doğrudan okuyan kodu güncelleyin.

## 2.9.0 (2026-09-01)

### Added
- Raporlar artık `status`'a göre filtrelenebilir.

## 2.8.4 (2026-08-28)

### Fixed
- `GET /reports?status=`, bilinmeyen bir durum için 400 yerine boş bir
  sayfa döndürüyordu.

Yukarıdan aşağıya okunduğunda, sürüm numarası ve bölüm etiketi aynı şeyi iki kez söyler, ve amaç tam olarak budur: sadece başlıkları tarayan bir okuyucu, tek bir satır açmadan doğru bir risk okuması alır.

Breaking change kuralı 1.0.0’dan önce de aynı şekilde geçerli mi?

Hayır, ve “bu gerçekten breaking mıydı” konusundaki kafa karışıklığının çoğu buradan gelir. SemVer, sıfırıncı majör sürümün, 0.y.z, ilk geliştirme için olduğunu açıkça belirtir: her şey her an değişebilir, ve public API kararlı sayılmamalıdır. Bir 0.4.0’dan 0.5.0’a sıçrama, spesifikasyonu ihlal etmeden breaking bir değişiklik taşıyabilir, çünkü majör sürüm garantisi ancak bir proje 1.0.0’ı gönderdiğinde başlar. Bir changelog girişi yine de okuyuculara neyin bozulduğu konusunda aynı dürüstlüğü borçludur; değişen tek şey, 1.0.0’a ulaşmadan önce sürüm numarasının kendisinin güvenilecek sinyal olmamasıdır.

Ürününüz ayrık sürümler göndermiyorsa ne olur?

Çoğu SaaS ürünü sürekli olarak dağıtır ve çağıran tarafa asla bir sürüm numarası göstermez, ki bu disiplin ihtiyacını ortadan kaldırmaz, sadece onu normalde taşıyacak sayıyı kaldırır. Changelog girişi tüm işi tek başına yapmalıdır: bir değişikliğin uyumsuz mu, ek mi, yoksa bir düzeltme mi olduğunu, semantic versioning’in kullandığı aynı üç kelimeyle, hatta onları takacak bir sürüm alanı olmadan bile açıkça söylemek. Bazı ekipler, changelog girişlerini asla doğrudan çağıran tarafa göstermeden, sadece bağlantı verilebilir bir şeye çapalamak için tamamen dahili bir sürüm tutar.

Bu, özellikle bir API changelog’una nasıl uygulanır?

Neredeyse başka her yerden daha katı bir şekilde, çünkü bir API’nin çağıranları koddur, beklenmedik bir değişikliği omuz silkip geçebilecek insanlar değil. API changelog’u: ne yayınlanır ve kim okur o belgenin tam biçimini ele alır; buradaki sürümleme disiplini, onun breaking ve ek bölümlerini dürüst tutan şeydir. Bir geçiş penceresi sırasında v1 ve v2’yi paralel sunmak gibi birden fazla sürümü aynı anda sunan bir API, tek bir paket yerine tüm arayüz ölçeğinde etkin bir şekilde semantic versioning uyguluyordur, ve aynı üç kelimelik kelime dağarcığı her giriş için hâlâ geçerlidir.

Keep a Changelog sürümleme hakkında ne söylüyor?

Doğrudan ismiyle semantic versioning’e bağlanır ve bu makalenin kullandığı aynı kategori kelime dağarcığını önerir: Added, Changed, Deprecated, Removed, Fixed, Security. Keep a Changelog, uygulamada ekiplerin genelde nerede saptığı dahil, bu spesifikasyonu benimsemeyi ele alır. Örtüşme tesadüf değildir: her iki spesifikasyon da aynı sorunu zıt uçlardan çözmeye çalışır, biri sürüm numarasını standartlaştırır, diğeri onu açıklayan girişi.

FAQ

Her changelog girişinin bir sürüm numarasına ihtiyacı var mı? Ürün sürümler gönderiyorsa evet, çünkü sayı bir okuyucunun önce girişi okumadan doğrudan “bu beni ne kadar etkiliyor”a atlamasına izin verir. Ürün sürüm alanı olmadan sürekli olarak dağıtılıyorsa, girişin ifadesi bu sinyali tek başına taşımalıdır.

MAJOR sıçraması ile uyumsuz değişiklik girişi arasındaki fark nedir? Aynı olayı iki şekilde tanımlamalıdırlar. Sürüm numarası makine tarafından okunabilir sinyaldir (çağıranın araçları buna tepki verebilir); changelog girişi, tam olarak neyin değiştiğinin insan tarafından okunabilir açıklamasıdır.

Bir PATCH sürümü uyumsuz olabilir mi? Tanım gereği olmamalıdır. Yine de biri yayınlandıysa, yayınlanan sürümü düzenlemeyin veya yeniden etiketlemeyin: SemVer FAQ uyumluluğu geri getiren yeni bir sürüm, ya da kırılma kalıyorsa yeni bir MAJOR yayınlamayı ve kullanıcıların atlaması gerektiğini bilmesi için sorunlu sürümü belgelemeyi söyler.

Tamamen dahili değişikliklerin bir sürüm sıçramasına ihtiyacı var mı? Hayır. Semantic versioning herkese açık arayüzü takip eder. Çağıran için gözlemlenebilir bir etkisi olmayan bir yeniden düzenleme, önemli bir mühendislik çalışması olsa bile ne bir sıçramaya ne de bir changelog girişine ihtiyaç duyar.

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

changeloop'ta ilgili sayfalar: Changelog oluşturucu, Geliştirici dokümantasyonu