NPM Paketlerinde Semantik Versiyonlama (SemVer)

Bu makale Frontend alanındaki deneyimlerimi ve yazılım geliştirme metodolojimi aktarmaktadır.

Genel Bakış

Yüzlerce farklı uygulamaya giden NPM paketinin güncellemelerinde hata oluşmaması için Breaking Change yönetimi, Git flow senkronizasyonu ve Semantic Versioning ilkelerini uyguladık.

Paylaşımlı bir NPM paketi ekosistemi yönetiyorsanız, en büyük kabusunuz masum görünen bir güncellemenin downstream projelerini çökertmesidir. Biz bunu acı tecrübeyle öğrendik: UI Kit'in Button bileşeninde prop adını değiştirdiğimizde, 3 farklı projenin build'i aynı anda kırıldı. O günden sonra Semantic Versioning'i (SemVer) katı bir disiplinle uygulamaya başladık.

SemVer'in kuralı basittir ama uygulaması disiplin gerektirir: MAJOR.MINOR.PATCH formatında, breaking change → MAJOR, yeni özellik → MINOR, hata düzeltme → PATCH. Bu kuralları changesets aracıyla otomatikleştirdik. Her PR'da developer bir changeset dosyası oluşturur ve değişikliğin seviyesini belirtir.

# Changeset oluşturma
bunx changeset
 
# Soru: Bu değişiklik hangi seviyede?
# ○ patch — Hata düzeltme
# ○ minor — Yeni özellik (geriye uyumlu)
# ● major — Breaking change

Her release'de otomatik oluşturulan CHANGELOG.md dosyası, tüketici projelerin geliştiricilerine hangi versiyonda ne değiştiğini net olarak gösterir.

## @huseyindol/ui-kit@2.0.0
 
### Major Changes
 
- **BREAKING**: Button bileşeninin 'type' prop'u 'variant' olarak yeniden adlandırıldı
- Migration guide: type="primary" → variant="default"
 
### Minor Changes
 
- Yeni Badge bileşeni eklendi
- Toast bileşenine 'duration' prop'u eklendi

Ayrıca lockfile stratejisi de kritiktir. Tüm projelerde bun.lock dosyası versiyon kontrolüne dahil ediliyor. Bu sayede "bende çalışıyor" mazeretleri sona eriyor, CI ortamında --frozen-lockfile flag'iyle tam deterministik build garantileniyor. PeerDependencies doğru tanımlanıyor ve React versiyon uyumsuzlukları derleme aşamasında yakalanıyor.

Bu içerik kişisel geliştirme laboratuvarımdan ve prodüksiyon maceralarımdan derlenmiştir.