Sürüm numaraları ne anlatır? Anlamsal sürümleme (SemVer) ve iyi bir değişiklik günlüğü

Bir yazılımın sürüm numarası yalnızca bir etiket değildir; kullanıcısına verilmiş bir sözdür. "Bu güncellemeyi yaparsan ne olacağını sana söylüyorum." Bu sözü standart bir biçimde vermenin en yaygın yolu anlamsal sürümleme (Semantic Versioning, kısaca SemVer).

Üç sayı, üç anlam

BÜYÜK.KÜÇÜK.YAMA
  2  .  4  .  1

• YAMA (patch): Geriye dönük uyumlu hata düzeltmeleri. 2.4.1 → 2.4.2: "Bir hatayı düzelttik, başka hiçbir şey değişmedi. Gönül rahatlığıyla güncelleyin."
• KÜÇÜK (minor): Geriye dönük uyumlu yeni özellikler. 2.4.2 → 2.5.0: "Yeni bir şey ekledik, ama mevcut kullanımınız bozulmayacak."
• BÜYÜK (major): Geriye dönük uyumluluğu bozan değişiklikler. 2.5.0 → 3.0.0: "Bir şeyler değişti; güncellemeden önce neyin değiştiğini okuyun ve kodunuzu uyarlamanız gerekebilir."

Bir sayı arttığında, sağındaki sayılar sıfırlanır: 2.5.3 → 3.0.0.

"Geriye dönük uyumluluğu bozmak" ne demek?

Mevcut kullanıcıların, kendi kodlarını değiştirmeden güncelleyememesi demektir. Örnekler:

• Bir fonksiyonun, sınıfın ya da API uç noktasının kaldırılması ya da adının değişmesi.
• Zorunlu yeni bir parametre eklenmesi.
• Bir fonksiyonun dönüş türünün ya da davranışının değişmesi.
• Desteklenen en düşük PHP, Node ya da işletim sistemi sürümünün yükseltilmesi.
• Bir yapılandırma ayarının adının ya da varsayılan değerinin değişmesi.

İsteğe bağlı yeni bir parametre eklemek, yeni bir fonksiyon ya da yeni bir uç nokta eklemek ise geriye dönük uyumludur ve küçük sürüm artışı gerektirir.

Özel durumlar

0.x sürümleri: 0.y.z sürümleri "henüz kararlı değil" anlamına gelir. Bu aşamada her şey değişebilir. Pek çok proje 0.x döneminde küçük sürüm artışlarını (0.3 → 0.4) kırıcı değişiklikler için kullanır. Composer ve npm de ^0.3.0 gibi bir kısıtı yalnızca 0.3.x sürümlerini kapsayacak şekilde yorumlar.

1.0.0: "Artık kararlı ve herkese açık bir arayüzümüz var" demektir. Bu noktadan sonra kırıcı değişiklikler büyük sürüm artışı gerektirir.

Ön sürümler: 3.0.0-beta.2, 3.0.0-rc.1 gibi etiketler, henüz kararlı olmayan sürümleri gösterir ve normal sürümlerden önce sıralanır.

SemVer'i doğru uygulamak

Kırıcı değişikliği yamada yayınlamayın. SemVer'in bütün değeri bu söze sadık kalmaktan gelir. 2.4.2 sürümünde bir fonksiyonun davranışını değiştirmek, ^2.4 kısıtıyla otomatik güncelleme yapan bütün kullanıcılarınızı habersizce etkiler.

Büyük sürüm artışından korkmayın. Bazı projeler kırıcı değişiklikleri "büyük sürüm çok önemli bir olay olmalı" düşüncesiyle küçük sürümlere gizler. Bu, kullanıcılara verilen sözü bozar. Kırıcı bir değişiklik varsa büyük sürüm artırılmalıdır, ne kadar küçük olursa olsun.

Kaldırmadan önce uyarın. Bir özelliği kaldırmadan önce bir küçük sürümde "kullanımdan kaldırılacak" (deprecated) olarak işaretleyin ve uyarı verin. Bir sonraki büyük sürümde kaldırın. Böylece kullanıcılarınıza hazırlanmak için zaman tanırsınız.

Herkese açık arayüzü tanımlayın. SemVer'in sözü, yazılımın herkese açık arayüzü için geçerlidir. Neyin herkese açık (belgelenen fonksiyonlar, API uç noktaları, yapılandırma ayarları), neyin iç ayrıntı olduğunu açıkça belirtin. İç ayrıntılar değiştiğinde sürüm kuralları uygulanmaz.

Uygulamalar için de geçerli mi?

SemVer, başkalarının bağımlılık olarak kullandığı kütüphaneler ve API'ler için tasarlanmıştır. Son kullanıcıya sunulan bir web uygulamasında ya da mobil uygulamada sürüm numaralarının bu kadar sıkı bir anlamı olmayabilir. Bazı projeler tarih tabanlı sürümleme (CalVer) kullanır: 2026.08, 26.8.1 gibi. Önemli olan, seçtiğiniz sistemin kullanıcılarınıza tutarlı bir şey anlatmasıdır.

Değişiklik günlüğü (changelog)

Sürüm numarası neyin değiştiğinin ne kadar önemli olduğunu söyler. Değişiklik günlüğü ise neyin değiştiğini anlatır.

Yaygın kullanılan "Keep a Changelog" biçimi:

## [2.5.0] - 2026-08-18

### Eklendi
- Siparişler PDF olarak dışa aktarılabiliyor.
- `fatura.gonder` kancası eklendi.

### Değişti
- Kargo ücreti hesaplaması artık desi ağırlığını da dikkate alıyor.

### Kullanımdan kaldırılacak
- `eski_fatura_olustur()` fonksiyonu 3.0.0 sürümünde kaldırılacak; yerine `Fatura::olustur()` kullanın.

### Düzeltildi
- Boş sepette ödeme sayfasının hata vermesi düzeltildi.

### Güvenlik
- Sipariş notlarında XSS açığı kapatıldı.

İyi bir değişiklik günlüğünün özellikleri:

• İnsanlar için yazılır, makineler için değil. Commit mesajlarının otomatik dökümü değil, kullanıcının bilmesi gerekenlerin özetidir. "Refactor X" ya da "Fix typo" gibi iç ayrıntılar buraya girmez.
• En yeni sürüm en üstte durur.
• Her sürümün tarihi yazılır.
• Kırıcı değişiklikler ve güvenlik düzeltmeleri öne çıkarılır. Bir kullanıcının günlükte en çok aradığı bilgi "Bu güncelleme benim kodumu bozar mı?" ve "Bu güncellemeyi hemen yapmam gerekir mi?" sorularının cevabıdır.
• Büyük sürümler için bir geçiş rehberi (upgrade guide) eklenir. Neyin değiştiği ve kodun nasıl uyarlanacağı, örneklerle.

Git etiketleri

Her sürümü Git'te bir etiketle işaretleyin:

git tag -a v2.5.0 -m "Sürüm 2.5.0"
git push origin v2.5.0

Composer ve npm gibi paket yöneticileri sürümleri bu etiketlerden okur. Etiketler, bir sürümde tam olarak hangi kodun yayınlandığını da kalıcı olarak kayıt altına alır.

Sürüm numaraları ve değişiklik günlükleri ilk bakışta bürokrasi gibi görünebilir. Ama yazılımınızı kullanan herkese, güncelleme yapmadan önce sorması gereken en önemli soruların cevabını verir: Ne değişti, ve bu benim için güvenli mi?