Anlamsal Sürümleme (SemVer): Sürüm Numarası Bir Söz Verir

Anlamsal sürümleme (SemVer), MAJOR.MINOR.PATCH biçimindeki sürüm numarasına net bir anlam yükler. Bu, estetik bir tercih değil bir sözleşmedir: kullanıcınız sürüm numarasına bakarak güncellemenin kodunu kırıp kırmayacağına karar verir. Yanlış artırılan bir hane, o güveni bir kerede tüketir.

Üç hane, üç söz

PATCH artırıldığında kullanıcı hiçbir şey değiştirmeden güncelleyebilmelidir: yalnızca hata düzeltmesi, davranış aynı.

MINOR artırıldığında yeni yetenek eklenmiştir ama mevcut kod aynen çalışır — geriye uyumlu ekleme.

MAJOR artırıldığında geriye uyumluluk bozulmuştur; kullanıcı kodunu gözden geçirmek zorundadır.

Neyin "kırıcı" olduğu tahmin edilenden geniştir

Ekiplerin en sık yanıldığı nokta budur. Aşağıdakilerin hepsi kırıcıdır ve MAJOR gerektirir:

// 1) Zorunlu parametre eklemek — mevcut çağrılar kırılır
- public function gonder(string $adres): bool
+ public function gonder(string $adres, string $konu): bool

// 2) Dönüş tipini daraltmak
- public function bul(int $id): ?array
+ public function bul(int $id): array          // null bekleyen kod kırılır

// 3) İstisna tipini değiştirmek — catch blokları artık yakalamaz
- throw new InvalidArgumentException(...)
+ throw new DomainException(...)

// 4) Varsayılan değeri değiştirmek — sessiz davranış değişikliği (en tehlikelisi)
- public function __construct(bool $katiMod = false)
+ public function __construct(bool $katiMod = true)

Dördüncüsü özellikle sinsidir: kod derlenir, testler geçer, ama kullanıcının uygulaması sessizce farklı davranmaya başlar. Sürüm notlarını dikkatle okumanın neden önemli olduğunu sürüm notlarını okuma sanatı yazımızda ele almıştık.

Geriye uyumlu ekleme nasıl yapılır?

// MINOR ile eklenebilir: yeni parametre İSTEĞE BAĞLI ve varsayılanı eski davranışı korur
public function gonder(string $adres, ?string $konu = null): bool
{
    $konu ??= $this->varsayilanKonu;   // eski çağrılar aynen çalışır

    // ...
}

Kırıcı bir değişikliği kademeli yaymak isterseniz, yeni davranışı müşteri bazlı yalıtımla önce tek bir gruba açabilirsiniz.

Kullanıcı tarafı: kısıt operatörleri

SemVer'in değeri, bağımlılık kısıtlarının anlam kazanmasıdır.

{
  "require": {
    "satici/kutuphane": "^1.4",   // >=1.4.0 <2.0.0  → MINOR ve PATCH serbest
    "satici/araclar":  "~1.4.2",  // >=1.4.2 <1.5.0  → yalnızca PATCH
    "satici/cekirdek": "1.4.2"    // tam sabitleme (genelde gereksiz katı)
  }
}

^ operatörü çoğu proje için doğru varsayılandır: güvenlik yamalarını otomatik alırsınız, kırıcı değişikliklerden korunursunuz. Ancak bu ancak kütüphane SemVer'e gerçekten uyuyorsa işe yarar. Bağımlılık seçerken bakılacak sinyalleri bağımlılık değerlendirme kontrol listesi yazımızda toplamıştık.

Sürüm notunu otomatikleştirin

Commit mesajlarını yapılandırırsanız sürüm numarası ve değişiklik günlüğü elle yazılmak zorunda kalmaz.

# Conventional Commits: tür(kapsam): açıklama
git commit -m "fix(mail): boş konu satırında çökme düzeltildi"      # → PATCH
git commit -m "feat(mail): ek dosya desteği eklendi"                # → MINOR
git commit -m "feat(mail)!: gonder() imzası değişti

BREAKING CHANGE: konu parametresi artık zorunlu."                    # → MAJOR

# Son etiketten bu yana kırıcı değişiklik var mı?
git log $(git describe --tags --abbrev=0)..HEAD --pretty=%B | grep -c "BREAKING CHANGE"

Katkı sürecini kolaylaştıran dosyalarla birlikte bu kurallar, dış katkıcıların doğru sürüm davranışını kendiliğinden benimsemesini sağlar — konuyu katkıyı kolaylaştıran dosyalar yazımızda ele almıştık. Kuralların resmî tanımı için semver.org Türkçe belgesi kısa ve nettir. API tarafındaki karşılığı içinse API sürümlemesi yazımıza bakabilirsiniz.

Sonuç

Sürüm numarası bir pazarlama aracı değil, kullanıcılarınıza verdiğiniz bir sözdür: "bu güncelleme seni kırmaz" ya da "dikkat et, kırabilir". Sözü tutmanın yolu, kırıcı değişikliğin tanımını geniş tutmaktan geçer — zorunlu parametre, daraltılan dönüş tipi, değişen istisna ve özellikle değiştirilen varsayılan değer. Commit mesajlarınızı yapılandırın, kırıcı değişiklikleri açıkça işaretleyin ve üretimde kullanılan bir kütüphaneyi 0.x'te bırakmayın. Bir sonraki yayınınızda sürüm numarasını artırmadan önce tek soru sorun: "Kullanıcım hiçbir şey değiştirmeden güncelleyebilir mi?"

Pratik Uygulama Kontrol Listesi

Bu yazıdaki önerileri kendi ekibinize uyarlarken aşağıdaki adımları sırasıyla uygulamanız, teoriden pratiğe geçişi kolaylaştırır:

1. Mevcut durumu ölçün. Değişiklik yapmadan önce bugünkü performansı/süreyi/hata oranını kaydedin; aksi halde iyileşmeyi kanıtlayamazsınız.
2. Küçük bir pilot seçin. Tüm sisteme veya tüm ekibe birden uygulamak yerine tek bir modülde veya tek bir sprintte deneyin.
3. Sonuçları ekiple paylaşın. Elde ettiğiniz veriyi (olumlu ya da olumsuz) kısa bir notla ekibe aktarın; kararın gerekçesi belgelenmemişse aynı tartışma birkaç ay sonra tekrar açılır.
4. Süreci tekrarlanabilir hale getirin. İşe yarayan pratiği bir kontrol listesine veya şablona dönüştürün ki yeni katılan ekip üyeleri de aynı standardı hızlıca öğrensin.

Sık Yapılan Yanlışlar

Bu konuda ekiplerin en çok düştüğü tuzak, çözümü tek bir kişiye ya da tek bir araca yüklemektir. Oysa kalıcı iyileşme, sürecin ekibin günlük rutinine (code review kontrol listesi, sprint planlama, onboarding dokümanı gibi) gömülmesiyle mümkün olur. İkinci yaygın hata ise "en iyi pratiği" olduğu gibi kopyalamaktır — başka bir ekipte işe yarayan bir yaklaşım, farklı bir ölçekte veya farklı bir teknoloji yığınında aynı sonucu vermeyebilir; önce kendi bağlamınızda küçük ölçekte test edin, sonra genişletin. Üçüncü tuzak ise ölçmeden karar vermektir: "daha iyi hissettiriyor" öznel bir gerekçedir, ekip içi tartışmalarda nesnel veriyle desteklenmeyen kararlar er ya da geç sorgulanır ve geri alınır. Son olarak, dokümantasyonu atlamak da sık görülen bir hatadır: bir kararın "neden" alındığı yazılı değilse, ekip altı ay sonra aynı tartışmayı sıfırdan yeniden yapmak zorunda kalır ve önceki deneyimden öğrenilenler kaybolur.

Sonuç

Anlamsal Sürümleme (SemVer): Sürüm Numarası Bir Söz Verir konusunda burada değindiğimiz noktalar, konuyu ilk kez ele alan ekipler için de deneyimli geliştiriciler için de pratik bir kontrol listesi görevi görür. anlamsal sürümleme üzerine çalışırken en çok fayda sağlayan yaklaşım, tek seferde her şeyi mükemmelleştirmeye çalışmak yerine küçük, ölçülebilir adımlarla ilerlemektir. Ekibinizde bu konuyu bir sonraki sprint retrospektifinde veya teknik tartışma toplantısında gündeme getirmenizi, burada anlatılan pratiklerden hangilerinin sizin bağlamınıza uyduğunu birlikte değerlendirmenizi öneririz. Sonuç olarak, doğru araçları seçmek kadar bunları ekip kültürüne oturtmak da başarıyı belirleyen asıl etkendir.