Changelog dosya formatları: JSON, YAML veya sadece Markdown

Çoğu ekip bir changelog’a Markdown dosyası olarak başlar çünkü bu en az direnç gösteren yoldur: bir pull request diff’inde okunabilir, GitHub’da hiçbir şey render etmeden okunabilir, ve bir README yazmış herkese tanıdıktır. Bu seçim, dosyayı bir insan dışında bir şeyin okuması gerekene, bir sayfa, bir widget, bir e-posta özeti, kadar iyi çalışır, ve o zaman format ücretsiz olmayı bırakır. Changelog otomasyonu yapısal gereksinimi genel olarak ele alır, bir tür, bir tarih, bir gövde ve bir bağlantı; bu yazı hangi dosya formatının bu yapıyı gerçekten sağladığını ve her birine oraya varmanın neye mal olduğunu ele alır.

Basit bir Markdown changelog’unda yanlış olan ne?

Bir şey onu tekrar alanlara ayrıştırması gerekene kadar hiçbir şey. Bir başlık, bir tarih ve altında bir madde işaretli liste, bir insan için okumak önemsizdir ve gerçekten güvenilir bir şekilde ayrıştırmak zordur, çünkü Markdown’un bir şeması yoktur: tarih başlıkta olabilir, ilk satırda kalın yazıyla olabilir, veya eski bir kayıtta tamamen eksik olabilir, ve bu varyasyonların her biri bir insanın doğru okuduğu ve bir ayrıştırıcının okumadığı geçerli Markdown’dır. Bir Markdown changelog’u otomatikleştiren ekipler genellikle bir kaydın biçimlendirmesi hafifçe kaydığında bile bozulan, regex tabanlı özel bir ayrıştırıcı yazmakla sonuçlanır, ki bu sık yaşanır, çünkü yazarken hiçbir şey tutarlılığı zorlamaz.

Yapılandırılmış bir format gerçekte size ne kazandırır?

Her kaydın aynı şekle sahip olduğuna dair, kayıt okunduğunda tahmin edilen değil, kayıt yazıldığında kontrol edilen bir garanti. Tanımlı bir şemaya sahip bir JSON veya YAML dosyası, tür, tarih, versiyon, hedef kitle, gövde, bağlantı, tıpkı katı bir API yanıtının yapacağı gibi gerekli bir alan eksikse gürültülü bir şekilde başarısız olur; bir Markdown dosyası orada olanı, doğru olsun olmasın, sadece render eder. Bu fark, bir betiğin bir akışı sıralamak için her kaydın tarihine ihtiyaç duyduğu ve kayıtların yarısının bunu farklı bir yerde tuttuğu güne kadar görünmezdir.

# CHANGELOG.yml
- date: 2026-09-05
  type: breaking
  version: v2
  audience: api
  body: "POST /invoices now rejects a currency mismatch instead of silently converting."
  link: /blog/api-changelog/

Bu, insan tarafından okunabilir dosyanın kaybolması gerektiği anlamına mı gelir?

Hayır, ve bir YAML veya JSON dosyasının aynı zamanda bir insanın bir pull request’te okuduğu şey olmasını sağlamaya çalışmak genellikle ters yönde bir hatadır: iç içe geçmiş JSON’un diff’ini incelemek, bir düz yazı cümlesini incelemekten daha kötüdür, ve bir ifade hatasını yakalamak için bir veri yapısını zihinsel olarak ayrıştırması gereken bir incelemeci, sonunda ifade hatalarını yakalamayı bırakacak bir incelemecidir. İki format bir arada var olabilir: yapılandırılmış veri, bir otomasyon pipeline’ının okuduğu doğruluk kaynağıdır, ve üretilmiş bir Markdown veya HTML render’ı, bir insanın gerçekten incelediği ve okuduğu şeydir, elle yanında tutulmak yerine yapılandırılmış dosyadan üretilir.

Hangi yapılandırılmış format elle düzenlemek için gerçekte daha kolay, JSON mu YAML mı?

YAML, bir üretici yerine elle kayıt yazan herkes için, çünkü JSON’un her string ve iç içe nesne için gerektirdiği tırnak işaretleme ve parantez eşleştirmeyi ortadan kaldırır. Ödünleşim, YAML’in boşluk duyarlılığının, JSON’un parantez uyuşmazlıklarının genellikle yapmadığı bir şekilde sessizce başarısız olmasıdır: bir JSON ayrıştırıcısı hatalı biçimlendirilmiş girdiyi doğrudan reddeder, YAML ayrıştırıcısı ise kötü girintilenmiş bir dosyayı kabul edip onu yanlış yapıya basitçe ayrıştırabilir, ki bu daha kötü bir başarısızlıktır çünkü hiçbir şey size bunun olduğunu söylemez. Kayıtlar sadece her zaman bir betik tarafından yazılıyorsa, bu ödünleşim büyük ölçüde ortadan kalkar ve JSON’un daha katı ayrıştırması daha güvenli varsayılan seçim haline gelir.

Bir changelog sayfasının, onu besleyen dosyadan ayrı kendi yapılandırılmış formatına ihtiyacı var mı?

Ayrı birine değil, farklı render edilmiş aynısına. Bir changelog sayfası, sayfanın kendisini bir JSON akışı ve schema.org işaretlemesi aracılığıyla nasıl makine tarafından okunabilir hale getireceğinizi ele alır; o akış üretilmiş bir çıktıdır, altta yatan dosyayla senkronize tutulacak ikinci bir doğruluk kaynağı değildir. Yapılandırılmış veriyi iki yerde, bir kaynak dosyada ve bir sayfanın akışında, elle tutmak, ikisinin nasıl ayrıştığıdır, bu yüzden burada verilen dosya formatı kararı, sonrasındaki her şeyin, sayfa, widget, e-posta, üretildiği tek şey olmalı, asla elle kopyalanmamalı.

Mevcut bir Markdown changelog’unu yapılandırılmış bir formata dönüştürmek geçiş maliyetine değer mi?

Genellikle sadece otomasyon gerçek hedef olduğunda, öncesinde değil. Bir GitHub README’sine Markdown dosyası yayınlayan tek kişilik bir proje gerçek bir otomasyon ihtiyacına sahip değildir, ve onu YAML’e dönüştürmek törenden başka bir şey satın almaz. Dönüşüm, birden fazla aşağı akış tüketicisinin, bir sayfa, bir özet e-postası, herkese açık bir akış, aynı veriyi okuması gerektiği anda kendini amorti eder, çünkü bu tam olarak bir Markdown ayrıştırıcısının tutarsızlıklarının sadece bakımı sıkıcı olmak yerine görünür şekilde yanlış çıktı üretmeye başladığı noktadır.

FAQ

Bir Markdown changelog’u formatı tamamen değiştirmeden ayrıştırılabilir hale getirilebilir mi? Kısmen, frontmatter ile: her kaydın başında küçük bir YAML bloğu (tarih, tür, versiyon), düz yazı için bir Markdown gövdesinin yanında. Bu, tüm kaydı JSON veya YAML’e zorlamadan bir ayrıştırıcının ihtiyaç duyduğu yapılandırılmış alanları elde eder, ve tam bir geçişe henüz hazır olmayan bir ekip için makul bir orta yoldur.

Dosya formatı SEO için veya bir changelog sayfasının nasıl sıralandığı için önemli mi? Doğrudan değil. Arama motorları render edilmiş sayfayı okur, kaynak dosyayı değil, bu yüzden dosya formatı onlar için görünmezdir; sayfanın kendisi için önemli olan, kendi hakkıyla makine tarafından okunabilir olup olmadığıdır, ki bu onu neyin ürettiğinden ayrı bir konudur.

Her changelog kaydı aynı dosyadan mı geçmeli, yoksa türler dosyalar arasında bölünebilir mi? Tek bir dosya, kayıt hacmi onu diff’lemek veya incelemek için hantal hale getirene kadar daha basittir; yıla veya kategoriye göre bölmek, tek bir dosyanın diff’leri mantıklı bir şekilde incelenemeyecek kadar büyüdüğünde makul bir güvenlik supabıdır, ama aşağı akıştaki herhangi bir şeyin “tüm kayıtları” tek bir liste olarak okuyabilmesinden önce bir birleştirme adımı ekler.

RSS için bir standart olduğu gibi standart bir changelog dosya formatı var mı? Geniş çapta benimsenmiş bir tane yok. Keep a Changelog bir Markdown kuralı önerir, ve birkaç aracın kendi formatı vardır; bir changeset paketi ve sürüm artışını adlandıran YAML frontmatter’lı bir Markdown dosyasıdır, yani yukarıda anlatılan frontmatter kalıbının ta kendisi. Bunların hiçbiri RSS okuyucularının RSS’i evrensel olarak anladığı gibi diğer araçların kutudan çıktığı gibi okuduğu bir format değildir.

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 araçları karşılaştırması, Changelog oluşturucu