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çıklamabiç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: 0olmazsa 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:
- Depo ayarlarında yalnızca squash merge'e izin verin.
- Squash commit mesajı olarak PR başlığını kullanın.
- 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/execeklentisiyle 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




