Yazılım Değişiklik Günlüğü (Changelog) Nasıl Hazırlanır?

Bir uygulamayı güncellediğinizde karşınıza çıkan "Bu sürümde neler değişti?" listesini çoğu kullanıcı okumadan geçer. Oysa bu kısa liste, aslında bir projenin hafızasıdır: hangi hatanın ne zaman düzeltildiğini, hangi özelliğin ne zaman eklendiğini, hangi işlevin artık desteklenmediğini gösterir. Bu belgeye genellikle changelog (değişiklik günlüğü) denir ve hem küçük bir ekip için hem de tek başına bir proje yürüten kişi için oldukça değerli bir alışkanlıktır.

Bu yazıda changelog'un ne olduğunu, neden tutulması gerektiğini, nasıl yapılandırılabileceğini ve sık yapılan hataları basit bir dille ele alıyoruz.

Changelog Nedir, Sürüm Notlarından Farkı Ne?

Changelog, bir yazılımın sürümleri arasında neyin değiştiğinin kronolojik bir kaydıdır. Her sürüm için "eklendi", "düzeltildi", "kaldırıldı" gibi başlıklar altında kısa maddeler halinde tutulur.

Buna benzer ama farklı amaçlı bir belge daha vardır: release notes, yani sürüm notları. İkisi sıklıkla birbirinin yerine kullanılsa da aralarında ince bir fark var:

• Release notes genellikle daha çok kullanıcıya dönük, pazarlama diline yakın, "bu sürümde sizi neler bekliyor" tonunda yazılır. Öne çıkan yeni özellikler vurgulanır, küçük düzeltmeler bazen hiç bahsedilmez.
• Changelog ise daha teknik ve kayıt odaklıdır. Amaç etkilemek değil, doğru ve eksiksiz belgelemektir. Küçük bir hata düzeltmesi bile, kullanıcıyı ilgilendiriyorsa listede yer alır.

Küçük projelerde bu ikisi tek bir dosyada birleştirilebilir; büyük ürünlerde ise genelde ayrı tutulur. Hangi yaklaşımı seçerseniz seçin, önemli olan okuyucunun ne beklediğini bilmesidir.

Neden Bir Changelog Tutulmalı?

Bazı geliştiriciler "zaten kod deposunda commit geçmişi var, neden ayrıca bir liste tutayım?" diye düşünebilir. Ama changelog'un birkaç somut faydası var:

• Şeffaflık: Kullanıcı, yazılımın üzerinde gerçekten çalışıldığını, hangi konularda ilerleme kaydedildiğini görür.
• Kullanıcı güveni: Düzenli güncellenen bir changelog, projenin terk edilmediğinin, aktif olarak sürdürüldüğünün somut kanıtıdır.
• Destek yükünü azaltma: "Bu özellik nereye gitti?", "Bu hata ne zaman düzeltildi?" gibi sorular, güncel bir changelog sayesinde büyük ölçüde önlenebilir. Kullanıcı, destek ekibine yazmadan önce kendi cevabını bulabilir.
• Ekip içi iletişim: Birden fazla kişinin çalıştığı projelerde changelog, herkesin diğerinin ne yaptığını takip etmesine yardımcı olur; özellikle uzaktan çalışan ekiplerde bu önemlidir.

İyi Bir Changelog'un Temel Bileşenleri

Bir changelog girdisinin okunaklı ve işe yarar olması için birkaç temel unsuru barındırması gerekir:

• Tarih ve sürüm numarası: Her girdinin başında hangi tarihte, hangi sürümün yayınlandığı açıkça belirtilmeli. Bu bilgi olmadan changelog bir zaman çizelgesi olmaktan çıkar.
• Kategoriler: Değişiklikleri türüne göre ayırmak okunabilirliği ciddi ölçüde artırır. Yaygın kullanılan kategoriler şunlardır:
  • Eklendi (yeni özellikler)
  • Değiştirildi (mevcut davranışta yapılan güncellemeler)
  • Düzeltildi (hata düzeltmeleri)
  • Kaldırıldı (artık desteklenmeyen özellikler)
• Kısa ve net maddeler: Her satır tek bir değişikliği anlatmalı. "Çeşitli düzeltmeler yapıldı" gibi belirsiz ifadeler yerine "Giriş ekranındaki şifre sıfırlama bağlantısı çalışmıyor sorunu düzeltildi" gibi somut cümleler tercih edilmeli.
• Denge: Gereksiz teknik jargona boğulmadan, ama önemli bir bilgiyi de atlamadan yazmak gerekir. Bu denge, hedef kitleye göre ayarlanabilir (bir sonraki başlıkta bu konuya döneceğiz).

Sürüm Numaralandırma ile Changelog İlişkisi

Changelog'u anlamlı kılan şeylerden biri de sürüm numaralarıyla kurduğu ilişkidir. Yaygın kullanılan anlamsal versiyonlama (semantic versioning) mantığında sürüm numarası üç basamaktan oluşur: major.minor.patch (örneğin 2.4.1).

Bu basamaklar rastgele artmaz, belirli bir mantığı takip eder:

• Major (büyük sürüm): Geriye dönük uyumluluğu bozan, yani eski kullanım şeklini çalışmaz hale getiren değişikliklerde artar.
• Minor (küçük sürüm): Geriye uyumlu yeni özellikler eklendiğinde artar.
• Patch (yama): Sadece hata düzeltmeleri yapıldığında artar.

Changelog, bu artışı gerekçelendiren belgedir. Yani bir kullanıcı "neden 2.3.0'dan 3.0.0'a geçildi?" diye merak ederse, changelog'daki "Kaldırıldı" veya "Değiştirildi" başlıklı maddeler bu büyük sıçramanın nedenini açıklar. Sürüm numarası ile changelog girdileri birbirini tamamlayan iki parça gibi düşünülebilir.

Yaygın Bir Format Önerisi: "Keep a Changelog" Mantığı

Changelog yazımında sıkça referans alınan bir yaklaşım, keepachangelog.com adresinde tanımlanan formattır. Bu yaklaşımın birebir kopyalanması gereken bir şablon olmaktan çok, genel bir mantık önerisi olduğunu belirtmek gerekir:

• En yeni sürüm her zaman belgenin en üstünde yer alır; en eski sürümler aşağıya doğru sıralanır.
• Her sürüm başlığı, tarih ve sürüm numarasıyla birlikte yazılır.
• Değişiklikler yukarıda bahsedilen kategoriler altında gruplanır.
• Henüz yayınlanmamış, üzerinde çalışılan değişiklikler için genellikle "Unreleased" (yayınlanmadı) gibi bir bölüm ayrılır; bu, ekibin bir sonraki sürüme ne hazırladığını görünür kılar.

Bu mantığın en büyük katkısı tutarlılıktır: okuyucu, hangi projenin changelog'una bakarsa baksın, benzer bir yapı bekleyebilir ve aradığı bilgiye hızla ulaşır.

Teknik Olmayan Kullanıcı vs Geliştirici: Dil Dengesi

Changelog'u okuyacak iki farklı kitle vardır ve bu ikisinin ihtiyaçları bazen çelişir:

• Son kullanıcı, genellikle "bu güncelleme beni nasıl etkiliyor?" sorusunun cevabını arar. Onun için sade, günlük dilde yazılmış kısa özetler yeterlidir: "Bildirim ayarlarındaki gecikme sorunu giderildi."
• Geliştirici veya ileri düzey kullanıcı ise daha ayrıntılı teknik bilgiye ihtiyaç duyabilir: hangi bileşenin, hangi koşulda, nasıl değiştirildiği gibi.

İki kitleyi aynı belgede dengelemenin birkaç yolu var:

• Ana changelog'u sade tutup, teknik detaylar için ayrı bir "geliştirici notları" bölümüne veya bağlantısına yer vermek.
• Madde başına kısa bir açıklama yazıp, gerekiyorsa parantez içinde teknik referans (örneğin ilgili modül adı) eklemek.
• Aşırı jargondan kaçınmak; teknik terim kullanmak gerekiyorsa kısa bir açıklama eklemek.

Hangi yöntem seçilirse seçilsin, amaç hiçbir okuyucuyu belgeyi anlamsız bulup terk etmeye itmemektir.

Otomatik Changelog Oluşturma Yaklaşımları

Büyüyen projelerde her sürüm için changelog'u elle yazmak zaman alıcı hale gelebilir. Bu noktada bazı ekipler, kod deposundaki commit mesajlarından otomatik olarak changelog üretme yöntemlerine başvurur.

Mantık şöyle işler: geliştiriciler kod değişikliklerini kaydederken belirli bir yapıya uyan mesajlar yazar (örneğin değişikliğin türünü belirten bir ön ek kullanılır). Bir araç bu mesajları tarayıp otomatik olarak kategorilere ayrılmış bir changelog taslağı oluşturur.

Bunun avantajları:

• Zaman tasarrufu sağlar, elle yazma yükünü azaltır.
• Commit disiplinini teşvik eder, çünkü herkes belirli bir formata uymak zorunda kalır.

Dezavantajları da var:

• Commit mesajları genellikle geliştiriciye hitap eder; bu yüzden otomatik üretilen metin bazen son kullanıcı için anlaşılmaz teknik jargon içerebilir.
• Otomatik üretim, önemli bir değişikliği önemsiz bir değişiklikle aynı satırda gösterebilir; insan gözden geçirmesi genelde hâlâ gereklidir.

Bu nedenle birçok ekip, otomatik üretilen taslağı bir başlangıç noktası olarak kullanıp, yayınlamadan önce son kullanıcı diline çevirerek düzenler.

Beta ve Kararlı Sürümlerin Changelog'a Yansıması

Bir yazılım geliştirilirken genellikle önce beta (test) sürümleri, ardından kararlı (stable) sürüm yayınlanır. Bu ayrım changelog'a da yansıtılmalıdır, çünkü beta sürümdeki bir not, kararlı sürümdeki notla aynı güvenilirlik seviyesinde değildir.

Pratikte şu yaklaşımlar işe yarar:

• Beta sürüm girdileri açıkça "Beta" veya "Ön sürüm" etiketiyle işaretlenmeli, böylece kullanıcı bunun henüz test aşamasında olduğunu anlar.
• Kararlı sürüme geçildiğinde, önceki beta aşamalarında yapılan tüm değişiklikleri özetleyen tek bir girdi eklemek faydalı olur; kullanıcı, ayrı ayrı beta notlarını takip etmek zorunda kalmaz.
• Kullanıcılar beta notlarını okurken, buradaki özelliklerin değişebileceğini veya kaldırılabileceğini göz önünde bulundurmalı; beta notu, kararlı sürüm vaadi değildir.

Sık Yapılan Hatalar

Changelog hazırlarken düşülen bazı yaygın tuzaklar var:

• Belirsiz ifadeler: "Çeşitli iyileştirmeler ve hata düzeltmeleri yapıldı" gibi cümleler hiçbir bilgi vermez. Kullanıcı neyin düzeldiğini bilmek ister.
• Tarih veya sürüm numarası eksikliği: Bu bilgiler olmadan changelog bir zaman çizelgesi olmaktan çıkar, hangi değişikliğin ne zaman geldiğini anlamak imkânsızlaşır.
• Önemli değişikliklerin gizlenmesi: Özellikle geriye dönük uyumluluğu bozan (kırıcı) değişiklikler, uzun bir listenin ortasına sıkıştırılmamalı; bu tür değişiklikler ayrı ve belirgin şekilde vurgulanmalı.
• Aşırı uzun, düzensiz listeler: Onlarca maddenin kategorisiz, sırasız bir şekilde alt alta dizilmesi okunabilirliği ciddi ölçüde azaltır. Kategorilere ayırmak ve gereksiz tekrarlardan kaçınmak önemlidir.

Changelog'un Yazılım Yaşam Döngüsündeki Yeri

Changelog, tek başına yaşayan bir belge değildir; yazılımın geliştirme, test, yayınlama ve bakım aşamalarının doğal bir çıktısıdır. Bir özellik geliştirilirken yapılan işler, test sürecinde beta notlarına, yayın sonrasında ise kararlı sürüm notlarına dönüşür.

Sürüm kontrol pratikleriyle (örneğin kod dallanma stratejileri veya sürüm etiketleme) de doğrudan bağlantılıdır: bir sürüm etiketlendiğinde, o etiketle ilişkili değişiklikler changelog'a işlenir. Bu sayede kod deposundaki teknik geçmiş ile kullanıcıya sunulan anlaşılır özet birbirini besler.

Uzun vadede düzenli tutulan bir changelog, projenin tarihçesini oluşturan değerli bir belgeye dönüşür. Yıllar sonra "bu özellik ne zaman eklenmişti?" sorusunun cevabı, genellikle commit geçmişini kazmaktan çok, changelog'a bakmakla çok daha hızlı bulunur.

Örnek Bir Changelog Girdisi Taslağı

Aşağıda, kurgusal bir uygulama için basit bir changelog örneği yer alıyor (gerçek bir ürünle ilgisi yoktur, yalnızca yapıyı göstermek amaçlıdır):

## [2.5.0] - 2024-03-12

### Eklendi
- Karanlık tema seçeneği ayarlar menüsüne eklendi.
- Dosya dışa aktarma işlemine PDF formatı desteği getirildi.

### Değiştirildi
- Ana ekran menüsünün yerleşimi, daha hızlı erişim için yeniden düzenlendi.

### Düzeltildi
- Uzun dosya adlarında listeleme ekranında oluşan kesilme sorunu giderildi.

### Kaldırıldı
- Eski dışa aktarma formatı (v1 API) desteği kaldırıldı; bkz. geçiş rehberi.

Bu taslakta dikkat edilmesi gereken noktalar:

• Tarih ve sürüm numarası başlıkta net şekilde belirtilmiş.
• Her madde tek bir değişikliği anlatıyor ve somut.
• "Kaldırıldı" gibi geriye dönük etkisi olan bir değişiklik, gizlenmeden ayrı bir kategoride vurgulanmış.
• Hem son kullanıcı hem de daha teknik bir okuyucu, kendi ilgi alanına giren bilgiyi kolayca bulabiliyor.

Sonuç olarak changelog, uzun ve gösterişli olmak zorunda değildir; net, tutarlı ve dürüst olması yeterlidir. Küçük bir projede bile bu alışkanlığı erken kazanmak, hem kullanıcıyla kurulan güveni güçlendirir hem de projenin kendi geçmişini takip etmesini kolaylaştırır.