16 Kasım 2026 PazartesiRSS

CI/CDYazılım

Conventional Commits ve semantic-release ile Otomatik Sürümleme

Aziz Özdemiroğlu

"Bu sürümde ne değişti?" sorusuna her seferinde commit geçmişini elle tarayarak cevap veriyorsanız, sürüm numarasını "hissederek" artırıyorsanız ve değişiklik günlüğü (changelog) hep eksik kalıyorsa, bu rehber tam size göre. Conventional Commits kuralıyla yazılan commit mesajları, semantic-release gibi araçlarla birleşince sürüm numarası, changelog ve yayın notları tamamen otomatik üretilir. Bu yazıda kuralları, araç kurulumunu ve CI entegrasyonunu adım adım anlatıyoruz.

Kısaca

  • Semantic Versioning (SemVer): MAJOR.MINOR.PATCH. Geriye uyumsuz değişiklik MAJOR, yeni özellik MINOR, hata düzeltmesi PATCH artırır.
  • Conventional Commits: tip(kapsam): açıklama biçiminde commit mesajları. feat → MINOR, fix → PATCH, BREAKING CHANGE → MAJOR.
  • commitlint + git hook ile kurala uymayan commit'ler daha yerelde reddedilir.
  • semantic-release ana dala her birleştirmede sürümü hesaplar, etiketi ve changelog'u oluşturur, paketi yayımlar.
  • Ekip alışkanlığı için en kolay yol: PR başlığını kurala uydurup squash merge yapmak.

Semantic Versioning'in kuralları

Değişiklik Örnek Sürüm
Geriye uyumsuz API değişikliği Bir fonksiyonun parametre sırası değişti 1.4.2 → 2.0.0
Geriye uyumlu yeni özellik Yeni bir seçenek eklendi 1.4.2 → 1.5.0
Geriye uyumlu hata düzeltmesi Yanlış hesaplama düzeltildi 1.4.2 → 1.4.3
Ön sürüm Beta yayın 2.0.0-beta.1

0.x.y sürümleri "henüz kararlı değil" anlamına gelir; bu aralıkta MINOR artışı da uyumsuz değişiklik içerebilir.

Conventional Commits biçimi

<tip>[isteğe bağlı kapsam][!]: <kısa açıklama>

[isteğe bağlı gövde]

[isteğe bağlı alt bilgi(ler)]

Yaygın tipler

Tip Anlamı Sürüme etkisi (varsayılan)
feat Yeni özellik MINOR
fix Hata düzeltmesi PATCH
perf Performans iyileştirmesi PATCH
docs Yalnızca dokümantasyon Yok
refactor Davranışı değiştirmeyen kod düzenlemesi Yok
test Test ekleme/düzeltme Yok
build, ci Derleme sistemi, CI yapılandırması Yok
chore Diğer bakım işleri Yok

Örnekler

feat(arama): Türkçe karakterli sorgularda vurgulama eklendi

fix(api): sayfalama son sayfada boş liste döndürüyordu

feat(auth)!: oturum token'ı artık çerezde değil Authorization başlığında

BREAKING CHANGE: İstemcilerin token'ı Authorization başlığında göndermesi gerekir.

Tipten sonra gelen ! veya alt bilgideki BREAKING CHANGE: ifadesi MAJOR sürüm artışı tetikler.

İyi commit mesajı için ipuçları

  • Açıklama emir kipinde ve kısa olsun (≈ 50–72 karakter).
  • "Ne" yerine "neden" gövdede anlatılsın.
  • Bir commit tek bir mantıksal değişiklik içersin.
  • Issue bağlantısını alt bilgiye ekleyin: Refs: #128.

Adım 1: commitlint ile kuralı zorunlu kılmak

npm install --save-dev @commitlint/cli @commitlint/config-conventional husky
echo "export default { extends: ['@commitlint/config-conventional'] };" > commitlint.config.mjs
npx husky init
echo 'npx --no -- commitlint --edit "$1"' > .husky/commit-msg

Artık kurala uymayan bir commit yerelde reddedilir:

$ git commit -m "düzeltmeler"
⧗   input: düzeltmeler
✖   subject may not be empty [subject-empty]
✖   type may not be empty [type-empty]

Yerel hook'lar atlanabileceği için aynı kontrolü CI'da da çalıştırın veya PR başlığını doğrulayan bir iş ekleyin.

Adım 2: semantic-release kurulumu

npm install --save-dev semantic-release @semantic-release/changelog @semantic-release/git

.releaserc.json:

{
  "branches": ["main", { "name": "beta", "prerelease": true }],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    ["@semantic-release/changelog", { "changelogFile": "CHANGELOG.md" }],
    "@semantic-release/npm",
    ["@semantic-release/git", {
      "assets": ["CHANGELOG.md", "package.json", "package-lock.json"],
      "message": "chore(release): ${nextRelease.version} [skip ci]"
    }],
    "@semantic-release/github"
  ]
}
Eklenti Görevi
commit-analyzer Son etiketten bu yana commit'leri okuyup sürüm artışını belirler
release-notes-generator Yayın notlarını üretir
changelog CHANGELOG.md dosyasını günceller
npm package.json sürümünü günceller, npm'e yayımlar ("private": true ise yayımlamaz)
git Değişen dosyaları geri commit'ler
github GitHub Release oluşturur, ilgili issue/PR'lara yorum yazar

npm'e yayımlamıyorsanız @semantic-release/npm eklentisini çıkarabilir veya npmPublish: false ayarını kullanabilirsiniz.

Adım 3: GitHub Actions ile otomatik yayın

name: release
on:
  push:
    branches: [main]
permissions:
  contents: write        # etiket ve release oluşturmak için
  issues: write
  pull-requests: write
  id-token: write        # npm provenance / trusted publishing için
jobs:
  release:
    runs-on: ubuntu-latest
    environment: release
    steps:
      - uses: actions/checkout@<SHA> # v5
        with:
          fetch-depth: 0     # tüm geçmiş ve etiketler gerekli
          persist-credentials: false
      - uses: actions/setup-node@<SHA> # v5
        with:
          node-version: 22
      - run: npm ci
      - run: npx semantic-release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Önemli ayrıntılar:

  • fetch-depth: 0 olmazsa semantic-release önceki etiketi bulamaz.
  • Ana dalda dal koruması varsa, @semantic-release/git'in geri commit'i engellenebilir. Bu durumda ya bu eklentiyi kullanmayın (changelog'u yalnızca GitHub Release'te tutun), ya da yayın için yetkilendirilmiş bir GitHub App token'ı kullanın.
  • Yayın işini korumalı ortam (environment) arkasına alarak kimin yayın tetikleyebileceğini sınırlayın.

Ekip iş akışı: squash merge ile basitleştirmek

Herkesin her commit'i kurala uygun yazmasını beklemek zor olabilir. Pratik çözüm:

  1. Depo ayarlarında yalnızca squash merge'e izin verin.
  2. Squash commit mesajı olarak PR başlığını kullanın.
  3. PR başlığını Conventional Commits'e göre doğrulayan bir CI işi ekleyin.

Böylece dal içindeki ara commit'ler serbest kalır, ana dala tek ve kurala uygun bir commit girer.

Monorepo ve npm dışı projeler

  • Monorepo: Her paket için ayrı sürüm gerekiyorsa commit kapsamını paket adıyla eşleştirin (feat(api): ..., fix(web): ...). semantic-release tek paket odaklıdır; monorepo'larda Changesets veya release-please gibi araçlar daha doğal bir akış sunar.
  • npm dışı projeler (Go, Python, Docker imajı): semantic-release yine sürümü hesaplayıp Git etiketi ve GitHub Release oluşturabilir. @semantic-release/exec eklentisiyle yeni sürüm numarasını derleme betiğinize aktarabilirsiniz:
["@semantic-release/exec", {
  "prepareCmd": "docker build -t ghcr.io/ornek/uygulama:${nextRelease.version} .",
  "publishCmd": "docker push ghcr.io/ornek/uygulama:${nextRelease.version}"
}]
  • Uygulamalar (kütüphane değil): Son kullanıcıya dağıtılan uygulamalarda da SemVer işe yarar: kullanıcı arayüzü değişikliklerinde MINOR, veri biçimi veya yapılandırma uyumsuzluklarında MAJOR artırın.

Sık yapılan hatalar

Hata Sonuç Çözüm
feat yerine fix kullanmak Yeni özellik PATCH olarak yayınlanır PR incelemesinde tipi de kontrol edin
Uyumsuz değişikliği işaretlememek Kullanıcıların kodu MINOR güncellemede kırılır ! veya BREAKING CHANGE: zorunlu, API değişikliği kontrol listesi
Sığ klon ile CI "No previous release" hatası, yanlış sürüm fetch-depth: 0
Elle etiket oluşturmak Otomatik sürüm hesabı bozulur Etiketleri yalnızca semantic-release oluştursun

Sonuç

Conventional Commits küçük bir disiplin, ama karşılığı büyük: sürüm numarası tartışması biter, changelog kendiliğinden yazılır, kullanıcılar neyin değiştiğini her zaman bilir. Önce commitlint ile kuralı yerleştirin, sonra semantic-release'i bir test deposunda deneyin, en son ana projenize taşıyın.

Kaynaklar

#Conventional Commits#Semantic Versioning#semantic-release#commitlint#Changelog#Git

Benzer Yazılar