Changelog nedir? Örnek bir kayıtla açıklama

Changelog, bir üründe neyin değiştiğinin tarihli kaydıdır ve değişikliği gönderen ekip için değil, değişiklikten etkilenen kişiler için yazılır. Her giriş bir değişikliği adlandırır, ne zaman yürürlüğe girdiğini söyler ve okuyucunun bununla ilgili ne yapması gerektiğini söyler, ki girişlerin çoğunda bu hiçbir şeydir. Bir changelog’u commit log’undan ayıran tam olarak bu son kısımdır: commit log, kodu yazanlar için bir kayıttır; changelog, onu kullananlar için bir kayıttır.

Changelog tam olarak nedir?

Tarihli girişlerin bir listesi, en yeni en üstte, her biri tek bir değişikliği okuyucunun üzerinde işlem yapabileceği terimlerle anlatır. Ekibin ne inşa ettiği değil, şimdi neyin farklı olduğu. “Faturalama servisi yeniden düzenlendi” bir commit mesajıdır. “Faturalar artık vergiyi ayrı bir satır olarak gösteriyor” bir changelog girişidir, çünkü okuyucuya kendi hesabında doğrulayabileceği bir şey söyler.

Format eskidir ve bilinçli olarak sadedir: her sürüm veya gün için bir başlık, altında kısa bir liste, bazen bir kategori etiketi. Keep a Changelog, bu biçim için en çok atıf alan spesifikasyondur ve bir spesifikasyonu atlayan çoğu projenin sonunda onun yerine commit geçmişini döktüğü için var olur, ki bu da okuyucunun geldiği sorudan farklı bir soruyu yanıtlar.

Bu beşi pratikte örtüşür, ama aynı belge değildir, ve fark, okunduğu anda kimin elinde tutulduğundadır. Changelog, aranmak ve sonradan tekrar bağlantı verilmek için inşa edilmiş olandır, bu yüzden girişleri diğerlerinden daha çok sabit tarihlere ve URL’lere ihtiyaç duyar.

Bir changelog girişi gerçekte neyi içerir?

Sırasıyla dört şey: neyin değiştiği, kullanıcının veya çağıran tarafın fark edeceği terimlerle ifade edilmiş; ne zaman yürürlüğe girdiği; hangi kategoriye ait olduğu (added, fixed, changed, removed yaygın dört kategoridir); ve önemli olduğunda, okuyucunun bununla ilgili ne yapması gerektiği. Daha fazla ayrıntıya bir bağlantı hoş karşılanır. Bir iç gerekçe paragrafı değil, çünkü okuyucu nedenini sormadı, neyi sordu.

## 2026-09-07

### Added
- Faturalar artık müşterinin hesap para biriminde, vergiyi ayrı bir
  satır olarak gösteriyor.

### Fixed
- Bir raporu CSV olarak dışa aktarmak, rapor 10.000 satırı aştığında
  artık son satırı düşürmüyor.

Bu biçim, iki satırlık bir güncellemeden bir sürümdeki yüz girişe kadar, yapıyı değiştirmeden ölçeklenir, ve bir formatın işe yarayıp yaramadığının gerçek testi de budur: yoğun bir haftada da sakin bir haftada da aynı şekilde okunuyor mu.

Changelog’u kim yazar, ve ne zaman?

Değişikliği yapan kişi, gönderildiği anda, bir hafta sonra biletlerden yeniden inşa eden teknik bir yazar değil. Koda dokunan kişi, kullanıcı için gerçekte neyin değiştiğini bilir; sonradan yazılan bir özet, gerçekte gönderilen şey yerine bileti anlatma eğilimindedir, ve bu genellikle gerçek kapsamdan daha geniş ya da daha dardır. Bazı ekipler bir giriş herkese açık olmadan önce bir inceleme adımı ekler, çoğunlukla içeri sızmış iç dil kullanımını yakalamak için, ve bu inceleme, giriş aynı gün yayınlanacak kadar hızlı olmalıdır.

Changelog nerede durmalı?

Kendi sayfasında, sabit bir URL’de, feed olarak dağıtılmış. Bir ayarlar menüsüne veya bir kod barındırıcısındaki bir release etiketine gömülmüşse, sadece nereye bakacağını zaten bilenlere ulaşır. Herkese açık bir sayfa bir destek biletinden bağlanabilir, bir incelemede alıntılanabilir veya abone olunabilir. Feed, sayfa kadar önemlidir: bir ürünün changelog’unu ayda bir kontrol eden bir okuyucu nadirdir, ona abone olan biri değildir, ve ikinciye sadece feed hizmet eder.

Sürüm notlarından nasıl farklıdır?

İkisi sürekli karıştırılır, ve birbirine karıştırmanın hiçbir okuyucuya iyi hizmet etmeyen bir belge ürettiği kadar da farklıdırlar. Changelog ve sürüm notları farkı baştan sona ele alır; kısacası, changelog eksiksiz, kronolojik kayıttır, sürüm notları ise bir güncellemenin sahip olmaya değer görünmesi için yazılmış küratörlü bir alt kümedir. Bir ürün genelde ikisine de ihtiyaç duyar, okuyucunun gününün farklı anlarına yönelmiş olarak.

Bir changelog’u okunmaya değer kılan nedir?

Kendi kapsamı hakkında somutluk ve dürüstlük. “Çeşitli hata düzeltmeleri”, bir okuyucuya sayfayı açmayı bırakmayı öğreten cümledir, çünkü doğrulayabileceği hiçbir şey vaat etmez. Küçük bir düzeltme için bile değişen tam davranışı adlandıran bir giriş, bir aboneliği canlı tutan giriştir. Bu disiplin ihmal edilenler için de geçerlidir: sadece kazanımları duyuran ve bozuk bir şey için asla bir düzeltmeyi duyurmayan bir changelog, changelog kılığına girmiş pazarlama gibi okunur, ve okuyucular bunu fark eder.

Sürümleme disiplini de önemlidir. Semantic versioning ve changelog’unuz, sürüm numarasının ve girişin nasıl uyumlu olması gerektiğini gösterir, böylece sürüm geçmişini tarayan bir okuyucu aynı sinyali iki farklı sinyal yerine iki kez alır.

Changelog’lar nasıl üretilir?

İki yolla, ve çoğu gerçek kurulum bir karışımdır. Otomatik üretim commit mesajlarını okur, genelde Conventional Commits formatında, ve kimse çıktıya dokunmadan bunları girişlere dönüştürür; conventional commits’ten changelog’a bu iş hattını ele alır. Küratörlü üretim, birinin her girişi elle yazması veya düzenlemesi demektir. Otomatik çıktı daha hızlıdır ve hiçbir zaman birleştirilmiş bir pull request’i kaçırmaz, ama her belirsiz commit mesajını kelimesi kelimesine devralır, bu yüzden otomasyon kullanan çoğu ekip, ham çıktıyı doğrudan göstermek yerine yayınlamadan önce hafif bir düzenleme adımını yine de korur.

FAQ

Her ürünün bir changelog’a ihtiyacı var mı? Değişiklikten etkilenen kullanıcıları olan her ürünün ihtiyacı vardır, ister SaaS uygulaması, ister dahili bir araç, ister herkese açık bir API olsun. Biçim uyum sağlar (bir API changelog’u bir tüketici uygulamasınınkinden farklı okunur), ihtiyaç sağlamaz.

Yazılım terimleriyle changelog nedir? Yukarıdakiyle aynı tanım: yazılımda neyin değiştiğinin, onu inşa edenler için değil kullananlar için yazılmış tarihli, kronolojik bir listesi.

Bir changelog commit’lerden otomatik olarak üretilebilir mi? Evet, ve birçok ekip tam olarak bunu yapar, genelde Conventional Commits formatındaki mesajlardan. Ödünleşim, üretilen bir girişin geldiği commit mesajı kadar açık olmasıdır, bu yüzden yayınlamadan önceki bir inceleme geçişi yeniden ifade edilmesi gerekenleri yakalar.

Changelog bir sürüm geçmişiyle aynı şey midir? Terimlerin birbirinin yerine kullanılacağı kadar yakın. Bir sürüm geçmişi bazen açıklama olmadan sadece sürüm numaraları ve tarihlerin bir listesidir; changelog her zaman neyin değiştiğini içerir.

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 örnekleri, Geliştirici dokümantasyonu