Semantic Versioning (Semver) Nedir? X.Y.Z Sürümü Nasıl Okunur?

Bir paketi güncellediğinizde ekibinizin "bu güncelleme projeyi bozar mı" sorusuna hızlı cevap bulması gerekir. Bu ihtiyacı çözmek için ortaya çıkan semantic versioning, sürüm numarasının kendisini bir iletişim aracına çevirir. Bu kurala npm, pnpm ve yarn gibi paket yöneticilerinin bağımlılık çözümlemesi de dayanır.

Semantic Versioning Nedir?

Bu kural, bir yazılım paketinin sürüm numarasını üç parçaya ayırıp her değişikliğin kapsamını standart bir biçimde ileten bir numaralandırma yöntemidir. X.Y.Z düzenindeki bu üç sayı sırasıyla major, minor ve patch değerlerini temsil eder ve her sayı farklı bir değişiklik türünü işaret eder.

Semver.org, kuralın resmi belirtimini yayınlar; "semver" kısaltması bu belirtimi kısaca adlandırır. Belirtim, sürüm numarasının nasıl artacağını ve iki sürümün nasıl karşılaştırılacağını açık kurallara bağlar, yorum ya da ekip alışkanlığına bırakmaz. Farklı ekipler böylece aynı numarayı aynı şekilde okur ve aynı sonuca ulaşır.

Belirtim ayrıca bir "herkese açık API" tanımından söz eder: belgelenmiş fonksiyonlar, veri türleri ve davranışlar bu kapsama girer. Bir paketin dahili kodu değişse de dışarıya açık bu yüzey değişmediği sürece semantic versioning kuralı bunu bir değişiklik saymaz.

Ekip içi bir tartışmada "bu değişiklik minor mu patch mi" sorusu çıktığında belirtim her zaman tek bir ölçüt sunar: dışarıdaki kod, güncellemeden sonra hiçbir düzenleme yapmadan çalışıyor mu? Cevap evet ise değişiklik en fazla minor, hayır ise major kabul eder.

X.Y.Z Sürüm Numarası Nasıl Okursunuz?

X.Y.Z biçimindeki sürüm numarasında X major, Y minor, Z ise patch değeridir ve soldan sağa önem sırasına göre dizilir. Örneğin 2.4.1 sürümünde major 2, minor 4, patch 1'dir; bu üç sayı soldan sağa önem sırasını yansıtır.

Deneyimli bir geliştirici bir bağımlılık listesine ilk baktığında bile sadece numaralara göz atarak hangi paketlerin yakın zamanda büyük bir değişim geçirdiğini, hangilerinin sakin kaldığını hızlıca ayırt eder ve bu okuma becerisi zamanla kod incelemesi kadar doğal bir alışkanlık haline gelir.

Bir sayı arttığında kendisinden sonra gelen sayılar sıfıra döner. Major artarsa minor ve patch değeri sıfıra döner, minor artarsa yalnızca patch sıfıra döner. Bu kural, numarayı okuyan kişinin geçmiş değişiklikleri tekrar saymasını gerektirmez.

Örneğin bir paket 1.9.0'dan 1.9.12'ye geçtiğinde yalnızca patch sayısı değişmiştir ve ekip bu güncellemeyi düşük riskli sayabilir. Aynı paket 1.9.12'den 2.0.0'a geçtiğinde ise major numarası değişir ve bu artış tek başına "dikkatli ol, bir şey kırılabilir" mesajını taşır.

• X (major): geriye uyumsuz, kırıcı değişiklikler.
• Y (minor): geriye uyumlu yeni özellikler.
• Z (patch): geriye uyumlu hata düzeltmeleri.

Major Sürüm Ne Zaman Artar?

Major sürüm, herkese açık API'de geriye uyumsuz bir değişiklik yapıldığında artar. Belirtim bunu net şekilde tanımlar: mevcut bir fonksiyonun davranışı, parametresi ya da dönüş değeri değişmişse ve eski kodu çalıştıran projeler hata alacaksa bu bir major değişikliktir.

Major artışı aynı zamanda bir uyarı sinyali taşır: güncellemeden önce değişiklik notlarını okumak ve kodu gözden geçirmek gerekir. Ekipler bu yüzden major sürüm geçişlerini genellikle planlı bir bakım penceresinde yapar, otomatik olarak yüklemez.

Bir kütüphane sahibi major sürümü artırmadan önce genellikle kullanıcılarına deprecation uyarısı verir; yani özelliği önce "kullanımdan kaldırılacak" diye işaretler, sonra bir sonraki major sürümde kaldırır. Bu iki aşamalı yaklaşım, mevcut kullanıcılara hazırlık süresi tanır.

Bir paket aynı anda birden fazla fonksiyonu değiştirse bile major sayı yalnızca bir kez artar; semantic versioning kuralı "kaç şey değişti" sorusuyla ilgilenmez, "en büyük değişiklik türü ne" sorusuyla ilgilenir. Bu yüzden küçük bir hata düzeltmesiyle birlikte gelen tek bir kırıcı değişiklik dahi tüm yayını major seviyesine taşır.

Minor Sürüm Ne Zaman Artar?

Minor sürüm, herkese açık API'ye geriye uyumlu yeni bir işlev eklendiğinde artar. Mevcut kod hiçbir değişiklik yapmadan çalışmaya devam eder, yalnızca yeni bir seçenek veya fonksiyon ortaya çıkar.

Belirtime göre bir ekip bir özelliği kullanımdan kaldırmaya başladığında da minor sürümü artırır; çünkü bu henüz kırıcı bir değişiklik değildir, sadece bir uyarıdır. Ekipler iç koddaki önemli iyileştirmeleri de minor artışıyla birlikte duyurabilir.

Örneğin bir kütüphane 2.3.0'da yeni bir yapılandırma seçeneği sunduğunda, bu seçeneği kullanmayan projeler hiçbir şey fark etmeden çalışmaya devam eder. Yalnızca o yeni seçeneği denemek isteyen ekip, belgeleri okuyup fonksiyonu isteğe bağlı olarak çağırır.

Patch Sürüm Ne Zaman Artar?

Patch sürüm, geriye uyumlu bir hata düzeltmesi yapıldığında artar. Belirtim hata düzeltmesini "yanlış davranışı düzelten iç bir değişiklik" olarak tanımlar; yani dışarıdan görünen API aynı kalır, sadece beklenmeyen davranış ortadan kalkar.

Ekipler patch sürümlerini genellikle en güvenli güncelleme olarak kabul eder, çünkü tanım gereği bu sürüm yeni bir işlev eklemez ve mevcut kullanımı bozmaz. Bu yüzden birçok ekip patch güncellemelerini otomatik olarak alır ve test sürecini kısa tutar.

Örneğin 1.2.5'ten 1.2.6'ya geçiş, genellikle bir hatayı düzeltir ve yeni bir davranış eklemez; bu yüzden ekip bu tür bir güncellemeyi gözden geçirmeden otomasyona bırakabilir. Buna karşılık bir "patch" olarak etiketlenen ama davranışı değiştiren bir yayın, semantic versioning kuralını yanlış uygular.

0.y.z Sürümü Ne Anlama Gelir?

Belirtim 0.y.z aralığını "ilk geliştirme" olarak tanımlar ve her şeyin her an değişebileceği anlamına gelir. Bir paket 0.y.z sürümündeyken herkese açık API henüz kararlılık kazanmaz.

Bu aşamada ekip, minor ve patch artışlarını 1.0.0 sonrasındaki kesin kurallarla aynı şekilde yorumlamaz; geliştirici henüz bir kararlılık sözü vermez. Bu nedenle 0.y.z sürümünde bir bağımlılığı üretim ortamına almadan önce değişiklik sıklığını takip etmek gerekir.

Birçok yeni açık kaynak proje, ilk kullanıcı geri bildirimlerini toplarken bilerek 0.y.z aralığında kalır. Proje sahibi, API'yi henüz kilitlemek istemediği için her yayını potansiyel bir kırıcı değişiklik olarak görür ve bunu kullanıcılarına belgelerde açıkça belirtir.

1.0.0 Sürümüne Geçiş Neden Önemli?

1.0.0 sürümü, herkese açık API'nin tanımlandığı ve artık bir kararlılık taahhüdünün başladığı noktadır. Belirtime göre ekip bu sürümden sonraki her değişikliği major, minor veya patch kurallarına göre değerlendirir.

Bir paketi 1.0.0 öncesinde kullanan projeler her güncellemede davranış değişikliğine hazırlıklı olmalıdır. 1.0.0 sonrasında ise geliştiriciler, aynı major numarası içinde kalan güncellemelerin API'yi bozmayacağını varsayar.

Bu geçiş aynı zamanda bir sorumluluk değişimidir: proje sahibi artık her kırıcı değişikliği major sürüm artışıyla açıkça duyurmayı taahhüt eder. Bu taahhüt olmadan kullanıcılar sürüm numarasına güvenemez ve her güncellemeyi baştan sona test etmek zorunda kalır.

Semantic Versioning'de Ön Sürüm Etiketleri (Alpha, Beta, RC) Nedir?

Ön sürüm etiketleri, patch numarasının hemen ardından bir tire ile eklenen ve noktayla ayrılan tanımlayıcılardır; örneğin 1.0.0-alpha.1 gibi. Belirtim alpha, beta veya rc kelimelerini zorunlu kılmaz, bunlar yalnızca geçerli tanımlayıcı örnekleridir.

Bir ön sürüm etiketi, o sürümün henüz kararlı sayılmadığını ve değişebileceğini gösterir. Tanımlayıcılar yalnızca ASCII harf, rakam ve tire taşıyabilir; boş olamaz ve sayısal bir tanımlayıcı başında sıfır bulunduramaz.

Bir ekip genellikle alpha etiketini en erken, kararsız aşama için, beta etiketini özellikleri tamamlamış ama testi süren aşama için, rc (release candidate) etiketini ise yayına çok yakın son kontrol aşaması için kullanır. Bu sıralama bir zorunluluk değil, yaygın bir alışkanlıktır.

Ön Sürüm Numaralarını Nasıl Sıralarsınız?

Ön sürümler, aynı X.Y.Z koduna sahip normal sürümden daha düşük önceliğe sahiptir; yani 1.0.0-beta her zaman 1.0.0'dan önce gelir. Birden fazla ön sürümü karşılaştırırken tanımlayıcıları soldan sağa tek tek kıyaslarsınız.

Sadece sayısal tanımlayıcıları sayısal olarak, diğerlerini ise ASCII sırasına göre karşılaştırırsınız ve sayısal olanları harf içerenlerden her zaman daha düşük kabul edersiniz. Belirtimdeki örnek sıralama şu şekildedir: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-alpha.beta, 1.0.0-beta, 1.0.0-beta.2, 1.0.0-beta.11, 1.0.0-rc.1 ve son olarak 1.0.0.

Bu sıralamayı bilmek, bir paket yöneticisinin "en yeni ön sürümü" doğru seçmesi için önemlidir. Bir ekip ^1.0.0-alpha gibi bir aralık tanımlarsa paket yöneticisi bu sıralama kurallarını kullanarak hangi ön sürümün en güncel olduğuna karar verir.

Build Metadata Nedir?

Build metadata, sürüm numarasının sonuna artı işaretiyle eklenen ve noktayla ayrılan ek bilgidir; örneğin 1.0.0+20130313144700 gibi. Bu alan genellikle derleme tarihi veya commit kimliği gibi bilgileri taşır.

Belirtim, build metadata'yı sürüm önceliği karşılaştırmasında göz ardı etmenizi söyler. Bu nedenle 1.0.0+a ve 1.0.0+b aynı önceliğe sahiptir; aralarındaki fark yalnızca ek bilgi içindir, sürüm sıralamasını değiştirmez.

Bir ekip build metadata'yı genellikle dahili izleme amacıyla kullanır; örneğin hangi derleme makinesinin veya hangi commit'in o paketi ürettiğini kaydeder. Kullanıcı tarafında bu bilgi görünse de güncelleme kararını etkilemez, çünkü paket yöneticisi onu karşılaştırmaya dahil etmez.

Bazı ekipler build metadata'yı dağıtım panosunda hangi sürümün üretimde çalıştığını hızlıca teşhis etmek için kullanır. Bir hata raporu geldiğinde destek ekibi, bu etikete bakarak sorunu hangi derlemenin ürettiğini saniyeler içinde bulur.

CI/CD Süreçlerinde Semantic Versioning Nasıl Kullanırsınız?

Bir dağıtım hattı, yeni bir sürüm yayınlamadan önce commit mesajlarına veya etiketlere bakarak hangi parçanın artacağına otomatik karar verebilir. Birçok araç, "fix:" ile başlayan commit'leri patch, "feat:" ile başlayanları minor, "BREAKING CHANGE" içerenleri ise major artışı olarak yorumlar.

Bu otomasyon, semantic versioning kuralını insan hatasından biraz daha bağımsız kılar; ekip her yayında numarayı elle seçmek zorunda kalmaz. Yine de araç yalnızca commit mesajlarını okur, kodun gerçekten ne değiştirdiğini anlamaz; bu yüzden geliştiricinin mesajı doğru sınıflandırması önemini korur.

Yayın öncesi bir onay adımı, commit mesajını yanlış okuyan bir otomasyonun hatalı bir major veya minor numarası üretmesini önler. Böylece ekip hem hız kazanır hem de sürüm numarasının güvenilirliğini korur.

Sürüm Aralıkları package.json İçinde Nasıl Çalışır?

package.json dosyasındaki bağımlılık satırları genellikle sabit bir sürüm yerine bir aralık belirtir; böylece paket yöneticisi uyumlu en güncel sürümü seçebilir. Npm'in resmi belgeleri bu aralıkları tilde ve caret gibi işaretlerle tanımlar.

Bir aralık tanımlamak, ekibin her güncellemede package.json dosyasını elle değiştirmesini önler. Paket yöneticisi bunun yerine kilit dosyasıyla birlikte hangi sürümün yüklendiğini kayıt altına alır.

Bir aralık tanımı yazarken ekip, bağımlılığın ne sıklıkla ve ne kadar tutarlı güncellendiğine göre karar verir. Sık değişiklik notu yayınlayan ve semantic versioning kuralına sıkı sıkıya bağlı bir paket için caret genellikle güvenlidir; nadir yayın yapan veya geçmişte kuralı yanlış uygulamış bir paket için daha dar bir aralık tercih edilir.

Caret (^) İşareti Ne Anlama Gelir?

Caret işareti npm belgelerine göre minor seviyesindeki güncellemeleri kabul eden bir aralık tanımlar; örneğin ^1.0.4 yazarsanız 1.x.x aralığındaki her sürümü kabul eder ama 2.0.0'a geçmez. Bu, major sürümün sabit kalacağı varsayımına dayanır.

Çoğu ekip caret aralığını varsayılan tercih olarak kullanır çünkü semantic versioning kuralına göre aynı major numarası içindeki güncellemeler API'yi bozmaz. Yine de 0.y.z paketlerinde caret davranışı farklılaşabilir, bu yüzden böyle paketlerde değişiklik notlarını kontrol etmek gerekir.

Örneğin ^0.4.2 yazan bir proje, npm'in sıfır major sürümlere özel kuralı nedeniyle 0.4.x aralığında kalır ve 0.5.0'a otomatik geçmez; çünkü 0.y.z aralığında minor sayı bile kararlı bir sözleşme sayılmaz. Bu küçük ayrıntı, 0.y.z bağımlılıklarla çalışan ekipleri sık sık şaşırtır.

Tilde (~) İşareti Ne Anlama Gelir?

Tilde işareti npm belgelerine göre patch seviyesindeki güncellemeleri kabul eden daha dar bir aralık tanımlar; ~2.2.0 yazarsanız yalnızca 2.2.x aralığındaki sürümleri kabul eder. Bu, caret'ten daha muhafazakar bir seçimdir.

Ekipler bir bağımlılığın minor sürümlerinde bile davranış değişikliğinden çekindiğinde tilde kullanır. Böylece ekip yalnızca hata düzeltmelerini otomatik alır, yeni özellikleri elle gözden geçirmeden kabul etmez.

Finans veya sağlık gibi hata toleransı düşük sistemlerde çalışan ekipler genellikle tilde'yi varsayılan aralık olarak seçer. Böyle bir sistemde beklenmedik bir minor değişiklik bile kabul edilemez bir risk oluşturur, bu yüzden ekip her yeni özelliği ayrı bir inceleme sürecinden geçirmeyi tercih eder.

Bir ekip hem hız hem güvenlik isterse karma bir yaklaşım da benimser: kritik bağımlılıklarda tilde, daha az riskli yardımcı paketlerde caret kullanır. Bu karma strateji, her bağımlılığa aynı kuralı dayatmak zorunda kalmadan riski bağımlılığın önemine göre ayarlar.

Semantic Versioning Bağımlılık Yönetimini Nasıl Kolaylaştırır?

Bu kural, bir bağımlılığın güncellemesinin güvenli olup olmadığını sürüm numarasına bakarak tahmin etmeyi mümkün kılar. Her paket yöneticisi böylece bir aralık kuralı tanımlayabilir ve insan onayı gerektirmeyen güncellemeleri otomatikleştirebilir.

Büyük bir projede onlarca bağımlılık varsa her birini elle takip etmek pratik değildir. Bu sayede ekip, yalnızca major değişiklikleri manuel incelemeye ayırır; minor ve patch güncellemelerini güvenle otomatikleştirir.

Birçok güvenlik taraması da bu kurala dayanır: bir açık bulunduğunda araç, düzeltmeyi içeren en düşük patch sürümünü önerir ve ekip major sıçramasına gerek kalmadan güvenlik açığını kapatır. Bu, semantic versioning'in güvenlik yama sürecini de hızlandırdığı anlamına gelir.

Semantic Versioning Kullanmayan Projelerde Ne Risk Var?

Semantic versioning kurallarına uymayan bir paket, sürüm numarasını anlamsız hale getirir ve kullanıcıların güncelleme kararını tahmin yoluyla vermesine yol açar. Bir "patch" güncellemesi aslında API'yi bozabilir, bu da aralık tabanlı otomatik güncellemeleri riskli kılar.

Böyle durumlarda ekipler genellikle bağımlılığı sabit bir sürüme kilitler ve her güncellemeyi elle test eder. Bu durum, semantic versioning'in sağladığı otomasyon avantajını ortadan kaldırır ve bakım yükünü artırır.

Bazı ekipler bu riski azaltmak için otomatik test paketini genişletir; her bağımlılık güncellemesinde uygulamanın tüm kritik yollarını test eder. Bu yaklaşım semantic versioning'in güvencesinin yerini tutmaz, ama kuralı uygulamayan bağımlılıklarla çalışırken zararı sınırlar.

Monorepo ve Çoklu Paketlerde Semantic Versioning Nasıl Uygularsınız?

Birden fazla paketi tek bir depoda tutan projelerde her paket kendi X.Y.Z numarasını taşıyabilir veya tüm paketler tek bir ortak sürümle hareket edebilir. İkinci yaklaşım paketler arası uyumu basitleştirir ama her küçük değişiklikte tüm paketlerin sürümünü artırır.

Çalışma alanı destekli paket yöneticileri, bir paket içindeki bağımlılığın hangi sürüm aralığını kullandığını workspace protokolüyle ayrıca yönetebilir. Bu yaklaşım, monorepo içindeki paketlerin birbirini her yayınlamada yeniden indirmesini gerektirmez.

1. Her paket için ayrı sürüm mü, ortak sürüm mü kullanacağınıza erken karar verin.
2. Paketler arası bağımlılığı workspace protokolü ile tanımlayın, sabit sürüm numarasıyla değil.
3. Yayın öncesi tüm paketlerin değişiklik notlarını tek bir listede toplayın.

Semantic Versioning Uygularken Sık Yapılan Hatalar Nelerdir?

En sık görülen hata, küçük görünen bir değişikliği "sadece patch" sayıp aslında API'yi kıran bir düzenlemeyi minor ya da major artışı yapmadan yayınlamaktır. Bu durum, aralığa güvenen her projeyi aynı anda etkiler.

Diğer bir hata, ön sürüm etiketlerini tutarsız kullanmaktır; örneğin bazı yayınlarda alpha, bazılarında beta kullanıp aralarında net bir kalite farkı tanımlamamaktır. Değişiklik notlarını her yayınla birlikte güncellemek bu hataların çoğunu önler.

• Her yayından önce herkese açık API'de ne değiştiğini listeleyin.
• Kırıcı bir değişiklik varsa major sürümü artırın, "küçük" olduğunu düşünseniz bile.
• Ön sürüm etiketlerini (alpha, beta, rc) tutarlı bir sırayla kullanın.

Bir başka yaygın hata, bir bağımlılığı güncellerken sadece sürüm numarasına bakıp changelog'u atlamaktır. Numara size değişikliğin türünü gösterir ama ayrıntısını anlatmaz; bu yüzden özellikle major ve bazı minor güncellemelerde changelog'u okumak gerçek riski ortaya çıkarır.

Semantic Versioning ve Değişiklik Notları (Changelog) Arasındaki İlişki Nedir?

Sürüm numarası bir değişikliğin türünü gösterir, ama değişikliğin ne olduğunu açıklamaz; bu boşluğu changelog doldurur. Bir ekip, her major, minor ve patch yayınında neyin değiştiğini kısa maddeler halinde yazdığında sürüm numarasının anlamı somutlaşır.

Changelog'u düzenli tutan bir proje, kullanıcılarının "bu güncellemeyi hemen alayım mı" sorusuna numaraya bakmadan da cevap bulmasını sağlar. Semantic versioning ile changelog birlikte kullanıldığında ekip, hem otomatik güncellemeyi hem de insan onayı gereken güncellemeyi aynı süreçte yönetebilir.

Bir changelog maddesi genellikle üç soruyu cevaplar: ne değişti, kimi etkiler ve nasıl geçiş yaparsınız. Bu üç soruyu eksiksiz cevaplayan bir changelog, sürüm numarasının verdiği kısa sinyali ayrıntılı bir eylem planına dönüştürür.

Kilit Dosyası (Lock File) Semantic Versioning'i Nasıl Tamamlar?

package.json dosyasındaki aralık, hangi sürümlerin kabul edilebilir olduğunu tanımlar; kilit dosyası ise o aralık içinden tam olarak hangi sürümün yüklendiğini sabitler. Bu ikili yapı, aynı projenin farklı bilgisayarlarda aynı bağımlılık ağacıyla çalışmasını garanti eder.

Kilit dosyası olmadan iki geliştirici aynı caret aralığını kullansa bile farklı günlerde farklı patch veya minor sürümlerini indirebilir. Bu fark küçük görünse de bazı hatalar yalnızca belirli bir sürümde ortaya çıkar ve ekip, "bende çalışıyor" sorunuyla karşılaşır.

Ekip kilit dosyasını depoya eklediğinde, sunucuda ve her geliştiricinin bilgisayarında birebir aynı bağımlılık ağacı oluşur. Bu tutarlılık, semantic versioning kuralının sağladığı tahmin edilebilirliği pratikte garantiye çevirir ve dağıtım sırasındaki sürprizleri azaltır.

Özel Yazılım Projelerinde Semantic Versioning Nasıl Fayda Sağlar?

Özel yazılım projelerinde kütüphane ve bağımlılık seçimleri baştan planlandığında semantic versioning kuralı sürpriz kırılmaları azaltır. Ekibimiz özel yazılım geliştirme projelerinde bağımlılık sürümlerini bu kurala göre takip eder ve güncelleme kararlarını buna göre planlar.

Bir projede paket yöneticisi seçimi de sürüm aralıklarının nasıl yorumlandığını etkiler. pnpm'in npm ve yarn'dan farkını anlattığımız yazıda bu konuyu daha ayrıntılı ele aldık. Bağımlılık çözümlemesi sırasında karşılaşılan çatışmalar için npm ERESOLVE hatası çözümü yazımız da yardımcı olur.

Hangi Araçlar Semantic Versioning Uyumluluğunu Otomatik Kontrol Eder?

Birçok geliştirme ortamı, bir paketin yeni yayınını eski sürümle karşılaştırıp herkese açık API'de kırıcı bir fark bulup bulmadığını otomatik tarar. Bu tür bir araç, geliştirici "patch" diye işaretlese bile gerçekte bir fonksiyon imzasının değiştiğini fark edip uyarı verir.

Bu kontrol, insan gözünün gözden kaçırdığı küçük ama kırıcı değişiklikleri yakalar; özellikle büyük bir API yüzeyine sahip kütüphanelerde elle kontrol pratik kalmaz. Ekip bu aracı dağıtım hattına eklediğinde, commit mesajını yanlış okuyan bir otomasyonun ürettiği yayın canlıya çıkmadan önce durur.

Bir Kütüphane İçin İlk Sürüm Numarasını Nasıl Seçersiniz?

Yeni bir paket yazan bir geliştirici genellikle 0.1.0 ile başlar; böylece henüz bir kararlılık taahhüdü vermeden geliştirmeye devam edebilir. Bazı ekipler ilk genel kullanıma 0.1.0 yerine doğrudan 1.0.0 vererek "bu API artık değişmeyecek" mesajını baştan verir.

Hangi seçimi yaparsanız yapın, kararı belgelerde açıkça yazmak önemlidir. Kullanıcılar bir paketin 0.y.z aralığında mı yoksa 1.0.0 sonrasında mı olduğunu bilmeden bağımlılık aralığı seçerse semantic versioning kuralının sağladığı güvenceyi tam olarak alamaz.

Bazı ekipler bu seçimi README dosyasının en üstüne bir rozet olarak ekler; böylece bir paketi değerlendiren geliştirici hemen o paketin hangi kararlılık aşamasında olduğunu görür. Bu küçük adım, sonradan doğacak yanlış beklentileri baştan önler ve ekip içindeki yeni bir geliştiricinin de aynı bilgiye saniyeler içinde erişmesini sağlar.

Sürüm Yönetimiyle İlgili Hangi Konulara Da Bakmalısınız?

Sürüm aralıklarının doğru çözülmesi için geliştirme ortamının tutarlı olması da önemlidir. Windows kullanan ekipler için WSL2 nedir yazımıza, ortamı container içine almak isteyenler için VS Code dev container yazımıza bakabilirsiniz. Apple Silicon üzerinde bazı paketlerin derlenmesinde Rosetta gerekip gerekmediğini anlattığımız yazı da ilgili bir kaynaktır.

Linux tarafında paket kaynaklarının hızını ve güvenilirliğini etkileyen Linux mirror seçimi konusuna da göz atabilirsiniz. Kod kalitesini ve API tasarımını etkileyen prensipler için SOLID prensipleri yazımız, bir yayın takvimini ekip içinde düzenlemek için ise geliştiriciler için proje yönetim araçları yazımız kardeş konularımızdır. ESLint ve Prettier yapılandırmaları çatıştığında bu çatışmayı nasıl çözeceğinizi de ayrı bir yazıda ele aldık.

Semantic versioning kuralının tam metnini ve karşılaştırma algoritmasını semver.org adresindeki resmi belirtimde, npm'in sürüm aralığı söz dizimini ise npm'in resmi belgelerinde okuyabilirsiniz.