Git etiketleri, sürümler ve changelog'unuz

Bir git etiketi, bir sürüm ve bir changelog girişi aynı olayın üç farklı kaydıdır, ve bunları karıştırmak bir changelog’un gerçekte gönderilenden sessizce uzaklaşmasına yol açar. Bir etiket bir commit’i işaretler. Bir sürüm o etiketi artifactlarla ve bir açıklamayla paketler. Bir changelog girişi, deponun dışındaki bir okuyucunun kullanabileceği terimlerle neyin değiştiğini açıklar. Genellikle zaman içinde birbirine yakın gerçekleşirler, ve tam da bu yüzden onları üç adım yerine tek bir adım gibi ele almak kolaydır, ve tam da bu yüzden boşluk ancak aylar sonra, biri “v2.4’te ne gönderildi” diye sorduğunda ve dürüst yanıt gerçek bir kazı gerektirdiğinde görünür hale gelir.

Üçü arasındaki gerçek fark nedir?

Bir etiket üçünün en mekanik olanıdır: git tag v2.4.0 ve tamamdır, içinde ne olduğunu bir şeyin açıklaması gerekmez. Bir sürüm bir açıklama ve genellikle indirilebilir artifactlar ekler, ve kitlesi hâlâ bir sürüm sayfasının ne olduğunu bilen geliştiricilerdir. Bir changelog girişi üçünden depoyu hiç açmayabilecek bir okuyucu için yazılan tek olanıdır, bu yüzden en çok editoryal dikkat gerektiren ve zaman baskısı altında en çok atlanan odur.

Her git etiketi bir changelog girişi gerektirir mi?

Hayır, ve ikisini bire bir ele almak yaygın bir hatadır. Bir etiket dahili bir kilometre taşını, bir release candidate’ı, veya çoğu kullanıcıya hiç ulaşmayan bir hotfix’i işaretleyebilir; bunların hiçbiri zorunlu olarak herkese açık bir giriş gerektirmez. Test, bir şeyin bir changelog’a girip girmeyeceğine karar veren aynı testtir: bir kullanıcı veya çağıran bunu fark eder mi veya önemser mi. Çoğu etiket bu testi geçer. Bazıları, sadece bir CI pipeline’ını tetiklemek için oluşturulan bir etiket gibi, hiç geçmez.

Her changelog girişi kendi etiketini gerektirir mi?

Her zaman değil, ve burada sürekli deploy eden ekipler ile versiyonlanmış paketler gönderen ekipler ayrılır. Günde birkaç kez deploy eden bir SaaS ürünü, deploy başına 1:1 etiket olmadan birden fazla deploy’u tarihli bir changelog girişi altında gruplandırabilir; bir paket kayıt defterinde yayınlanan bir kütüphane genellikle yayınlanan versiyon başına bir etikete ihtiyaç duyar. Go modules ve Swift Package Manager versiyonları doğrudan etiketlerden çözer; npm veya PyPI’da yayınlanan versiyonu kayıt defteri tutar, ve etiket herkesin o versiyonu kaynağına geri eşlemesini sağlar. Bağımsız olarak versiyonlanan birden fazla pakete sahip bir repository, buna tüm repo için bir kez değil, paket bazında karar vermelidir; monorepo changelog’ları etiket öneklerinin ve changelog kapsamının klasör sınırlarına değil paket sınırlarına göre nasıl bölünmesi gerektiğini ele alır. Semantic versioning ve changelog’unuz versiyon numarasının kendisinin changelog kategorilerine nasıl eşlenmesi gerektiğini ele alır; etiketler bir versiyon numarasını gerçek koda karşı doğrulanabilir kılan mekanizmadır.

Bir sürüm açıklaması changelog girişiyle nasıl ilişkilenmeli?

Aynı metin olabilirler, ama sadece ikisinin kitlesi gerçekten aynıysa, ki bu göründüğünden daha nadirdir. Bir kod barındırıcısındaki bir sürüm sayfası neredeyse yalnızca geliştiriciler tarafından okunur; bir üründe changelog’u okuyan teknik olmayan kullanıcılar da varsa, sürüm açıklamasını kelimesi kelimesine kopyalamak, sade dil versiyonuna ihtiyaç duyan bir okuyucuya dahili terimler ve koda odaklı bir ifade gönderir. En temiz desen: changelog girişini birincil, okuyucuya yönelik artifact olarak yazmak, ve sürüm açıklamasının ya ona bağlanmasına ya da orada zaten rahat olan kitle için daha kısa, daha teknik bir özet tutmasına izin vermek.

# Sürüm v2.4.0 (GitHub, geliştiriciler için)
Raporlar pipeline'ını yeni agregasyon motoruna yükseltir. Müşteriye
yönelik özet için changelog'a bakın:
https://example.com/changelog#v2.4.0

## 2026-09-07 (Changelog, müşteriye yönelik)
### Added
- Raporlar artık bir milyondan fazla satırı olan hesaplar için bile
  bir saniyeden kısa sürede yükleniyor.

Aynı sürüm, iki belge, her biri kendi okuyucusu için kendi ifadesiyle.

Changelog girişi gerçekte nereden gelir?

İki başlangıç noktasından, ve çoğu gerçek pipeline ikisinin bir karışımıdır. Etiket anında commit mesajlarından üretilebilir, ki bu hızlıdır ve birleştirilmiş bir pull request’i asla kaçırmaz; conventional commits’ten changelog’a o pipeline’ı baştan sona ele alır. Veya etiketten tamamen ayrı olarak, kodun birleştirildiği an yerine bir özelliğin tamamlanmış sayıldığı ana göre zamanlanarak elle yazılabilir. Üretilen girişler tutarlıdır ama her belirsiz commit mesajını devralır; elle yazılan girişler daha nettir ama onları gerçekten yazacak birine ihtiyaç duyar. Otomasyon kullanan çoğu ekip, ham metin nereden gelmiş olursa olsun, Keep a Changelog, uygulamada’nın önerdiği aynı disiplinle, üretilen metin herkese açık giriş olmadan önce yine de hafif bir düzenleme geçişi tutar.

Üçü senkronizasyondan çıktığında ne bozulur?

Okuyucunun önce kontrol ettiği şeye olan güven. Karşılık gelen bir changelog girişi olmadan var olan bir etiket, changelog okuyucusunun tarafından bakıldığında, o hafta hiçbir şey olmamış gibi görünür. Karşılık gelen bir etiket veya sürüm olmadan bir changelog girişi, üretimde bir sorunu debug eden birinin bir giriş yayınlandığında canlı olan tam kodu checkout etmesini imkansız kılar. Çözüm mükemmel otomasyon değil, eşleme için tek bir gerçek kaynağıdır: sürüm sürecinin kendi kontrol listesi olsa bile, gönderilebilir bir değişikliğin onu tanıtan aynı commit veya pull request’te üçünü de aldığını söyleyen bir yer.

FAQ

Changelog girişleri git etiketlerinden otomatik olarak üretilmeli mi? Bir başlangıç noktası olabilirler, ama tek başına bir etiket okuyucuya yönelik hiçbir açıklama taşımaz, sadece bir commit aralığı. Otomatik üretim, kullanılabilir bir şey üretmek için sadece etiketin varlığını değil, o aralıktaki commit mesajlarını okumak zorundadır.

Her sürümü etiketlemezsek ne olur? O zaman changelog girişi birincil kayıt haline gelir, ve yine de bir tarih ve, ürünün bir tanesi varsa, bir versiyon numarası taşımalıdır, böylece giriş karşılık gelen bir etiket olmadan bile sonradan bir okuyucunun başvurabileceği bir şey olarak kalır.

Ön sürüm etiketleri (v2.4.0-rc.1 gibi) changelog girişlerine sahip olmalı mı? Genellikle hayır. Bir release candidate dahili veya beta testi içindir, ve onun için bir changelog girişi okuyucuları hiç açıklandığı gibi gönderilmeyebilecek versiyonlar için giriş beklemeye alıştırır. Girişleri genel kullanılabilirliğe ulaşan etiketlere ayırın.

Tek bir changelog girişi birden fazla git etiketini kapsayabilir mi? Evet, ve sık sık etiketleyen ekipler için genellikle öyle olmalıdır. İlgili etiketleri, bir özelliği birden fazla okuma boyunca parçalayan etiket başına ince bir giriş yayınlamak yerine, net değişikliği açıklayan tarihli bir giriş altında gruplandırın.

Bu yazıdaki teknik iddialar bağımsız olarak kontrol edilmedi. Yanlış bir şey varsa bize söyle, düzeltelim.

changeloop'ta ilgili sayfalar: Changelog oluşturucu, Geliştirici dokümantasyonu