Git'ten Sürüm Üretmek: MinVer, Nerdbank.GitVersioning ve GitVersion Karşılaştırması

Sürüm notu: Bu yazıdaki örnekler .NET 10 (SDK 10.0.402), Git 2.54, MinVer 8.0.0, Nerdbank.GitVersioning 3.10.94, GitVersion 6.8.2 ve actionlint 1.7.12 ile denenmiştir. Workflow actionlint ile doğrulandı; GitHub'da koşulmadı.

Önce Tahmin Et

Sitedeki serilerin ortak örnek uygulaması Bookstore'un (bir online kitapçı) Bookstore.Contracts paketinde sürümü elle yazmaktan vazgeçtik ve MinVer'i ekledik. MinVer, sürümü Git tag'lerinden hesaplayan küçük bir MSBuild paketi:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="MinVer" Version="8.0.0" PrivateAssets="all" />
  </ItemGroup>

</Project>

Repository'de v1.0.0 tag'i var ve ondan sonra iki commit atılmış. Paketi oluşturuyoruz:

$ git log --oneline --decorate
669bffa (HEAD -> main) feat: add publisher
eda29a1 fix: trim isbn
802d782 (tag: v1.0.0) feat: book dto
$ dotnet pack src/Bookstore.Contracts -o out

Paketin adı ne olur? 1.0.0 mı, 1.0.1 ile başlayan bir pre-release mi, yoksa başka bir şey mi?

  Successfully created package '.../out/Bookstore.Contracts.0.0.0-alpha.0.2.nupkg'.

MinVer tag'i hiç görmedi. Varsayılan ayarda tag adının doğrudan bir SemVer (Semantic Versioning; uyumluluk anlamı taşıyan sürüm kuralları) sürümü olmasını bekliyor; v1.0.0 ise v harfiyle başladığı için geçerli bir sürüm değil. Hiç tag bulamayınca varsayılan 0.0.0-alpha.0'ı kullanıyor ve arkasına ilk commit'ten bu yana atılan commit sayısını ekliyor. Hata yok, uyarı yok; yalnızca yanlış bir paket adı. Bu yazıda sürümü Git geçmişinden türeten üç aracı aynı senaryoda yan yana koyup böyle sessiz farkların nereden çıktığına bakıyoruz.

Üç Yaklaşım

Üç araç da aynı property'leri dolduruyor: Version, PackageVersion, AssemblyVersion, FileVersion, InformationalVersion. Bir önceki yazıda bunları elle ya da komut satırından verdik; şimdi bir MSBuild target'ı build sırasında Git'e bakıp hesaplıyor. Farkları sürüm bilgisinin nerede durduğunda:

• MinVer: sürümün tek kaynağı tag. Tag'li commit o sürümü alır, sonraki commit'ler bir sonraki patch'in pre-release'i olur. Repository'de ek dosya yok.
• Nerdbank.GitVersioning (NBGV): major ve minor version.json dosyasında yazılı; patch, o dosyanın son değiştiği commit'ten bu yana atılan commit sayısı, yani git height. Tag gerekmiyor.
• GitVersion: son tag'den başlıyor, ama nasıl artırılacağına branch'in tipine ve GitVersion.yml'daki kurallara göre karar veriyor. En esnek, en çok yapılandırma isteyen seçenek.

Karşılaştırmayı adil yapmak için üçünde de aynı senaryoyu oynattık: ilk commit, v1.0.0 tag'i, iki commit, bir feature branch'i ve merge, ardından bir sonraki sürüm. Her adımda dört property'yi şu komutla okuduk ve tabloya döktük:

dotnet build src/Bookstore.Contracts -t:Build \
  -getProperty:Version -getProperty:AssemblyVersion \
  -getProperty:FileVersion -getProperty:InformationalVersion

MinVer: Yalnızca Tag

Tahmin bölümündeki sorunun çözümü tek satır: tag önekini söylemek.

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <MinVerTagPrefix>v</MinVerTagPrefix>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="MinVer" Version="8.0.0" PrivateAssets="all" />
  </ItemGroup>

</Project>

Aynı senaryonun sonuçları:

step                    Version            AssemblyVersion  FileVersion  InformationalVersion
first commit            0.0.0-alpha.0      0.0.0.0          0.0.0.0      0.0.0-alpha.0+acc482c1766a…
tag v1.0.0              1.0.0              1.0.0.0          1.0.0.0      1.0.0+acc482c1766a…
2 commits later         1.0.1-alpha.0.2    1.0.0.0          1.0.1.0      1.0.1-alpha.0.2+30568b6a5f56…
feature/stock-dto       1.0.1-alpha.0.3    1.0.0.0          1.0.1.0      1.0.1-alpha.0.3+f7f235a553e9…
main, after merge       1.0.1-alpha.0.3    1.0.0.0          1.0.1.0      1.0.1-alpha.0.3+abf0b06cb6ef…
tag v1.1.0-rc.1         1.1.0-rc.1         1.0.0.0          1.1.0.0      1.1.0-rc.1+abf0b06cb6ef…
1 commit after rc       1.1.0-rc.1.1       1.0.0.0          1.1.0.0      1.1.0-rc.1.1+8925957e4404…
tag v1.1.0              1.1.0              1.0.0.0          1.1.0.0      1.1.0+8925957e4404…

Kurallar sade. Tag'li commit tag'in sürümünü alıyor. Kararlı bir sürümden (RTM; Release To Manufacturing, yani pre-release etiketi taşımayan son sürüm) sonraki commit'ler bir sonraki patch'in pre-release'i oluyor: 1.0.1-alpha.0, sonuna da tag'den bu yana commit sayısı (height) ekleniyor. Pre-release bir tag'den (v1.1.0-rc.1) sonra ise etiket korunup yalnız height ekleniyor: 1.1.0-rc.1.1. Hangi parçanın artırılacağını MinVerAutoIncrement ile minor ya da major'a çevirebilir, alpha.0'ı MinVerDefaultPreReleaseIdentifiers ile değiştirebilirsin.

İki ayrıntıya dikkat et. Birincisi AssemblyVersion: MinVer onu her zaman Major.0.0.0 yapıyor. Bir önceki yazıda elle kurduğumuz kural kendiliğinden geliyor. İkincisi tablonun ortasındaki iki satır: feature branch'teki commit ile main'deki merge commit'i farklı commit'ler, ama ikisi de 1.0.1-alpha.0.3 sürümünü alıyor. MinVer branch adını hesaba katmıyor. İki branch'ten aynı sürüm numarasıyla paket yayınlamaya kalkarsan ikincisi feed'de reddedilir; bu yüzden MinVer kullanan ekipler pre-release paketleri genelde yalnız main'den yayınlıyor.

.NET 8'den beri SDK'nın InformationalVersion'a commit SHA'sını (Git'in commit'i tanımlayan hash değeri) eklediğini görmüştük; MinVer'in hesapladığı değerin arkasına yine +sha geliyor. MinVer'in .NET dışı projeler için bir CLI aracı da var (minver-cli); aynı repository'deki bir npm paketine aynı sürümü vermek istediğinde işe yarıyor.

Nerdbank.GitVersioning: version.json ve Git Height

NBGV'nin bakış açısı farklı: sürümün sabit kısmı repository'de bir dosyada duruyor ve her commit kendiliğinden yeni bir patch üretiyor.

{
  "$schema": "https://raw.githubusercontent.com/dotnet/Nerdbank.GitVersioning/main/src/NerdBank.GitVersioning/version.schema.json",
  "version": "1.0",
  "publicReleaseRefSpec": [
    "^refs/heads/main$",
    "^refs/heads/v\\d+(?:\\.\\d+)?$"
  ],
  "nugetPackageVersion": {
    "semVer": 2
  }
}

"version": "1.0" major ve minor'ı veriyor; üçüncü sayı git height. publicReleaseRefSpec, hangi ref'lerden yapılan build'lerin "public release" sayılacağını tanımlıyor; bunların dışındaki build'lerin sürümüne commit id'si eklenir. Aynı senaryo, bu kez tag'siz:

step                    Version              AssemblyVersion  FileVersion
first commit            1.0.1                1.0.0.0          1.0.1.31635
2 commits later         1.0.3                1.0.0.0          1.0.3.11548
feature/stock-dto       1.0.4-g75ee34d545    1.0.0.0          1.0.4.30190
main, after merge       1.0.5                1.0.0.0          1.0.5.49450

Main'deki her commit, pre-release etiketi olmayan, yayınlanabilir bir sürüm alıyor: 1.0.3, 1.0.5. Feature branch'i public ref olmadığı için -g75ee34d545 ekini alıyor; iki branch'in aynı sürümü üretme ihtimali böylece ortadan kalkıyor. FileVersion'ın dördüncü bölümü de commit id'sinden türetilen bir sayı. AssemblyVersion ise varsayılan olarak Major.Minor.0.0; MinVer'den bir adım daha sık değişiyor. Değeri komut satırından görmek için local tool olarak nbgv:

$ dotnet tool install nbgv --version 3.10.94
$ dotnet nbgv get-version
Version:                      1.0.5.49450
AssemblyVersion:              1.0.0.0
AssemblyInformationalVersion: 1.0.5+c12a1f0d5a
NuGetPackageVersion:          1.0.5
NpmPackageVersion:            1.0.5

Release branch'i açmak da araçla yapılıyor. version.json'ı 1.1-rc'ye çekip prepare-release çalıştırınca NBGV bir v1.1 branch'i açıp oradaki sürümü kararlı 1.1'e çeviriyor, main'i ise 1.2-alpha'ya geçiriyor:

$ dotnet nbgv prepare-release
v1.1 branch now tracks v1.1 stabilization and release.
main branch now tracks v1.2-alpha development.

step                    Version              AssemblyVersion
main, "1.1-rc"          1.1.1-rc             1.1.0.0
main after prepare      1.2.2-alpha          1.2.0.0
v1.1 branch             1.1.2                1.1.0.0
v1.1 + 1 fix            1.1.3                1.1.0.0

$ dotnet nbgv tag
Remember to push to a remote: git push origin v1.1.3

Dosyadaki version değiştiğinde height sıfırlanıyor; bu yüzden main'de 1.2.2-alpha, release branch'inde 1.1.2 görüyoruz. NBGV'nin tag komutu mevcut commit'e hesaplanan sürümün tag'ini atıyor ama push'lamıyor; tag NBGV'de sonuç, kaynak değil.

GitVersion 6: Branch'e Göre Hesaplama

GitVersion, sürümü tag'den alıp branch'in tipine göre artırıyor. v6'da yapılandırma bir workflow şablonuyla başlıyor (GitFlow/v1, GitHubFlow/v1, deneysel TrunkBased/preview1); dosya yoksa GitFlow varsayılıyor. Bookstore'un tek main branch'li akışı için:

workflow: GitHubFlow/v1
assembly-versioning-scheme: Major

assembly-versioning-scheme: Major satırını sonradan ekledik. GitVersion'ın varsayılanı MajorMinorPatch; ilk denemede AssemblyVersion her patch'te değişti ve bir önceki yazıdaki binding sorununa davetiye çıkardı. Senaryonun sonuçları:

step                    Version              AssemblyVersion  FileVersion
tag v1.0.0              1.0.0                1.0.0.0          1.0.0.0
2 commits later         1.0.1-2              1.0.0.0          1.0.1.0
feature/stock-dto       1.0.1-stock-dto.1    1.0.0.0          1.0.1.0
main, after merge       1.0.1-4              1.0.0.0          1.0.1.0
"feat!: ..." commit     1.0.1-5              1.0.0.0          1.0.1.0
tag v1.1.0              1.1.0                1.0.0.0          1.1.0.0
"+semver: major" commit 2.0.0-1              2.0.0.0          2.0.0.0

GitHubFlow şablonunda main'in etiketi boş; tag'lenmemiş commit'ler 1.0.1-2 gibi, son tag'den bu yana commit sayısını taşıyan pre-release'ler alıyor. Feature branch'i, branch adından türetilen stock-dto etiketini alıyor. CLI aracının çıktısı hesaplamanın ayrıntısını gösteriyor:

$ dotnet tool install GitVersion.Tool --version 6.8.2
$ dotnet gitversion
{
  "AssemblySemVer": "1.0.0.0",
  "BranchName": "feature/stock-dto",
  "FullSemVer": "1.0.1-stock-dto.1+3",
  "InformationalVersion": "1.0.1-stock-dto.1+3.Branch.feature-stock-dto.Sha.fccfb26dc8c0ec6b132351c01c68b930953a5eb0",
  "PreReleaseLabel": "stock-dto",
  "SemVer": "1.0.1-stock-dto.1",
  "VersionSourceDistance": 3,
  "VersionSourceSemVer": "1.0.0",
  ...
}

Tablodaki iki satır önemli. feat!: ile başlayan commit sürümü değiştirmedi; GitVersion varsayılan olarak Conventional Commits'i okumuyor, kendi +semver: major (ya da minor, patch) işaretine bakıyor. Mesajında bu işaret olan commit sürümü 2.0.0-1'e taşıdı. Conventional Commits'ten sürüm üretmeyi bir sonraki yazının konusu olan release araçlarına bırakmak daha temiz.

v5'ten geçenler için v6'nın en önemli değişiklikleri: branch'teki pre-release ayarının adı tag'den label'a, is-mainline ise is-main-branch'e döndü; Mainline mode'u kaldırıldı. Deployment mode adları da yer değiştirdi: eski ContinuousDelivery'nin karşılığı artık ManualDeployment, eski ContinuousDeployment'ın karşılığı ContinuousDelivery. Eski bir GitVersion.yml'ı olduğu gibi taşırsan aynı isim artık başka bir davranış anlamına gelebiliyor. NuGetVersion ve LegacySemVer gibi bazı çıktı değişkenleri de kaldırıldı; bunları kullanan pipeline script'leri boş değer alır.

Bir de .NET 8 SDK'sıyla çakışma var. GitVersion InformationalVersion'a kendi build metadata'sını yazıyor, SDK ise arkasına commit SHA'sını bir kez daha ekliyor:

1.0.1-2+Branch.main.Sha.1516ad602086b14bba49306f1bcd7b037796d901.1516ad602086b14bba49306f1bcd7b037796d901

GitVersion kullanan projelerde SDK'nın eklemesini kapatmak yeterli:

<PropertyGroup>
  <IncludeSourceRevisionInInformationalVersion>false</IncludeSourceRevisionInInformationalVersion>
</PropertyGroup>

CI'da Shallow Clone Tuzağı ve fetch-depth: 0

Üç araç da Git geçmişini okuyor, ama CI sistemleri hız için çoğu zaman geçmişsiz bir kopya çekiyor. actions/checkout varsayılan olarak yalnız son commit'i getiriyor (fetch-depth: 1). Tag'den sonra bir commit atılmış repository'yi --depth 1 ile klonlayıp üç aracı denedik:

$ git clone --depth 1 <repository-url> contracts

# MinVer: hata yok, sürüm yanlış
# tam clone: 1.1.1-alpha.0.1
Version: 0.0.0-alpha.0

# Nerdbank.GitVersioning: build düşer
error MSB4018: Nerdbank.GitVersioning.GitException: Shallow clone lacks the objects required to calculate version height. Use full clones or clones with a history at least as deep as the last version height resetting change.

# GitVersion (GITHUB_ACTIONS=true ile)
WARN [26-11-14 6:59:29:08] An error occurred:
Repository is a shallow clone. Git repositories must contain the full history. See https://gitversion.net/docs/reference/requirements#unshallow for more info.

Sonuçlar üç farklı davranış gösteriyor. NBGV build'i durduruyor; sorun hemen fark ediliyor. GitVersion bir build server ortamında (burada GITHUB_ACTIONS=true) shallow clone'u reddediyor; aynı klasörde yerel bir terminalden çalıştırınca ise hata vermeden geçmişin görünen kısmından yanlış bir sürüm hesapladı. En tehlikelisi MinVer: hiçbir uyarı vermeden 0.0.0-alpha.0'a düşüyor ve bu sürümle bir paket üretiyor. Detaylı log'u açınca sebep görünüyor:

$ dotnet build src/Bookstore.Contracts -p:MinVerVerbosity=detailed
...
  MinVer: 1 commits checked.
  MinVer: No commit found with a valid SemVer 2.0 version prefixed with 'v'. Using default version 0.0.0-alpha.0.
  MinVer: Using { Commit: bb7a151, Tag: '', Version: 0.0.0-alpha.0, Height: 0 }.
  MinVer: Calculated version 0.0.0-alpha.0.

Çözüm üçü için de aynı: CI'da tam geçmişi çekmek. Bookstore.Contracts'ın CI workflow'u:

name: contracts-ci

on:
  push:
    branches: [main]
    tags: ['contracts/v*']
  pull_request:

permissions:
  contents: read

jobs:
  pack:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        # MinVer tag'lere ve geçmişe ihtiyaç duyar
        with:
          fetch-depth: 0
          filter: tree:0
      - uses: actions/setup-dotnet@v6
        with:
          global-json-file: global.json
      - run: dotnet pack src/Bookstore.Contracts -c Release -o artifacts
      - uses: actions/upload-artifact@v7
        with:
          name: contracts-nupkg
          path: artifacts/*.nupkg

filter: tree:0, MinVer dokümanının önerdiği bir optimizasyon: commit'leri ve tag'leri getiriyor, dosya ağaçlarını yalnız gerektiğinde indiriyor. Azure Pipelines'ta karşılığı checkout adımındaki fetchDepth: 0. Bu workflow actionlint ile doğrulandı; GitHub'da koşulmadı.

Branch Stratejisiyle Uyum

Hangi aracın uygun olduğu büyük ölçüde branch stratejine bağlı. Git & GitHub serisinin "Git ile Ekip Çalışması: Branch Stratejileri, Rulesets ve Conventional Commits" yazısında üç akışı karşılaştırmıştık.

Trunk-based development'ta tek uzun ömürlü branch main ve sürüm, main'deki bir commit'e tag atılarak çıkıyor. MinVer bu akışa en doğal uyan araç: tag at, sürüm o. NBGV de iyi çalışıyor, ama main'deki her commit'e kararlı bir sürüm verdiği için "her merge bir release" anlayışına daha yakın.

Release branch'li akışta (main'de geliştirme, release/1.x ya da v1.1 branch'inde stabilizasyon) NBGV'nin prepare-release komutu işin büyük kısmını yapıyor: branch'i açıyor, iki taraftaki version.json'ı güncelliyor. MinVer'de aynı akışı release branch'inde tag atarak yürütüyorsun; main'in bir sonraki minor'a geçtiğini söylemek için MinVerMinimumMajorMinor kullanılıyor.

GitFlow gibi develop, release, hotfix ve feature branch'lerinin her birinin farklı sürüm davranışı istediği bir akışta GitVersion'ın branch tabanlı kuralları anlamlı hâle geliyor. Akış sadeleştikçe bu esnekliğin bedeli, yani yapılandırmayı anlamak ve sürümler arasında taşımak, öne çıkıyor.

Karar Tablosu

Bookstore'da trunk-based çalışıyoruz ve repository bir monorepo: API, web ve Contracts aynı yerde. Contracts için MinVer'i seçtik ve tag önekini paket adıyla ayırdık; API'nin app/v... tag'leri Contracts'ın sürümünü etkilemiyor:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <!-- Sürüm contracts/v1.2.0 gibi tag'lerden gelir -->
    <MinVerTagPrefix>contracts/v</MinVerTagPrefix>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="MinVer" Version="8.0.0" PrivateAssets="all" />
  </ItemGroup>

</Project>

$ git tag contracts/v1.0.0
$ dotnet pack src/Bookstore.Contracts -c Release -o artifacts
  Successfully created package 'artifacts/Bookstore.Contracts.1.0.0.nupkg'.

Tek bir paket ve sade bir akış için MinVer yeterli. Birden çok paketin kendi hızında sürüm aldığı ve height'ın yalnız ilgili klasördeki değişikliklerle artması gereken bir monorepo'da NBGV'nin pathFilters özelliği daha uygun. Ekip zaten GitFlow kullanıyor ve branch tipine göre farklı pre-release etiketleri istiyorsa GitVersion.

Üretimde Dikkat

Yerelde ve CI'da aynı sürümü üret. Yerel bir klon genelde tam geçmişe sahip, CI ise değil; bu yüzden "bende 1.1.1-alpha.0.1, CI'da 0.0.0-alpha.0" farkı en sık görülen şikâyet. fetch-depth: 0'ı workflow şablonuna koy ve ilk kurulumda CI'ın ürettiği sürümü yerel sonuçla karşılaştır.

Tag'leri annotated at ve korumaya al. Sürümün kaynağı tag olduğunda bir tag'i silip başka commit'e taşımak, yayınlanmış bir paketin hangi koddan derlendiğini belirsizleştirir. Git & GitHub serisinin "Git Tag ve Release" yazısında tag'leri taşımanın sonuçlarını konuşmuştuk; release tag'lerini bir ruleset ile korumak iyi bir önlem.

Pre-release paketleri kimin yayınlayacağına karar ver. MinVer iki branch'e aynı sürümü verebildiği için pre-release yayınını main ile sınırla; NBGV ve GitVersion'da feature branch sürümleri ayırt edilebilir ama her pull request'in feed'e paket göndermesi feed'i kısa sürede kirletir.

Docker build'lerinde .git klasörünü unutma. Image içinde dotnet pack ya da dotnet publish çalıştırıyorsan, .dockerignore .git'i dışarıda bırakıyorsa araçlar geçmişi göremez. Sürümü dışarıda hesaplayıp -p:Version= ile build argümanı olarak geçmek daha öngörülebilir.

Sık Düşülen Tuzaklar

Tag önekini söylememek. Tahmin bölümündeki durum: v1.0.0 tag'i MinVer için yok hükmünde. NBGV'de tag zaten kaynak değil; GitVersion'ın varsayılan tag-prefix'i ise v'yi kabul ediyor. Aynı tag'ler üç araçta farklı sonuç veriyor.

Tag'i yanlış commit'e atmak. Sürüm commit'i yerine bir önceki commit'e atılan v1.1.0, son düzeltmeyi içermeyen bir 1.1.0 paketi üretir ve doğru commit 1.1.1-alpha.0.1 olur. Tag atmadan önce git log --oneline -1 ile commit'i kontrol et; mümkünse tag'i CI'daki release adımına bırak.

İki aracı aynı projede karıştırmak. Bir geliştirici MinVer'i eklerken repository'de eski bir version.json ve NBGV paketi kalmışsa iki target da aynı property'leri yazar ve sonuç target sırasına bağlı olur. Bir araç seç, diğerinin paketini ve dosyasını sil.

Conventional Commits'in sürümü değiştirdiğini sanmak. feat!: mesajı GitVersion'da tek başına major artırmıyor, MinVer ve NBGV ise commit mesajına hiç bakmıyor. Commit mesajından sürüm hesaplamak release araçlarının işi.

InformationalVersion'ı parse eden kodu kırmak. GitVersion ile SDK'nın ikisi birden build metadata yazınca değer iki SHA içeriyor; +'dan sonrasını tek bir commit sanan kod yanlış sonuç verir.

Küçük Bir Deneme

★☆☆ MinVer'li projede MinVerAutoIncrement'i minor yap ve tag'den iki commit sonraki sürümü önce tahmin et, sonra -getProperty:Version ile kontrol et.

★★☆ NBGV'ye "pathFilters": ["src/Bookstore.Contracts"] ekle. Yalnız web/ altındaki bir dosyayı değiştiren commit Contracts'ın sürümünü artırıyor mu? Aynı deneyi MinVer'le yap ve farkı açıkla.

★★★ Kendi bir repository'ni --depth 1 ile klonla ve kullandığın aracın ne yaptığını gözle. Ardından CI workflow'una, üretilen sürüm 0.0.0 ile başlıyorsa build'i durduran bir adım ekle.

Sürümü artık Git'ten alıyoruz; ama "bu sürümde ne değişti?" sorusunun cevabı hâlâ commit log'unda dağınık duruyor. Bir sonraki yazıda Conventional Commits'ten sürüm ve CHANGELOG üreten release otomasyonunu, release notlarını ve deprecation politikasını ele alıyoruz.