CHANGELOG.md: içine ne girer ve nasıl güncel tutulur

CHANGELOG.md, bir deponun kökünde duran ve her yayımlanan versiyon için neyin değiştiğini, projenin bir kullanıcısının üzerine harekete geçebileceği terimlerle listeleyen bir Markdown dosyasıdır. Dosyayı yükseltip yükseltmemeye karar verenler, yükseltmeden sonra hata ayıklayanlar ve onu projenin sayfasında gösteren paket kayıtları ile release araçları okur. Çoğu projenin izlediği biçim keepachangelog.com’da anlatılandır: en yeni versiyon en üstte, onun üstünde bir Unreleased bölümü ve Added, Changed, Deprecated, Removed, Fixed ve Security altında gruplanmış girdiler.

CHANGELOG.md dosyası nedir?

Bir projenin insanların okuyabileceği geçmişidir; her seferinde bir versiyon, kodun yanında tutulur ki onunla birlikte gönderilsin. git log’dan kitlesi ve seçimiyle ayrılır: git log her commit’i onları yazan insanlar için kaydeder, changelog ise bir kullanıcının fark edeceği değişiklikleri, onları yazmamış kişi için yazılmış halde kaydeder. Dahili bir değişkeni yeniden adlandıran bir commit’in changelog satırı yoktur. Varsayılan zaman aşımını değiştiren bir commit’in vardır, diff tek karakter olsa bile.

Dosya depo kökünde tam o adla yaşar, çünkü araçlar onu orada arar. GitHub depo sayfasından ona bağlantı verir, npm ve PyPI pakete dahil edildiğinde onu gösterir, release-please ve semantic-release gibi release araçları onu yerinde okur ve yazar. Küçük harfli changelog.md ve CHANGES.md insanlar için de çalışır, ama bazı araçlar yalnızca kanonik adı arar.

Tam bir CHANGELOG.md neye benzer?

Kısa ve doğru bir örnek, uzun bir açıklamadan daha değerlidir. Bu örnek Keep a Changelog 1.1.0 düzenini, numaralar için de semantic versioning’i izler.

# Changelog

Bu projedeki tüm kayda değer değişiklikler burada listelenir.
Biçim: Keep a Changelog. Versiyonlar: Semantic Versioning.

## [Unreleased]

### Added
- `deploy` üzerindeki `--dry-run` bayrağı planı uygulamadan
  yazdırır.

## [2.3.1] - 2026-10-01

### Fixed
- Arama artık tire içeren sorgularda başarısız olmuyor. 2.3.0'dan
  beri bozuktu.

### Security
- Statik dosya işleyicisindeki bir path traversal düzeltildi.
  Kullanıcı yüklemelerini sunuyorsanız bugün yükseltin.

## [2.3.0] - 2026-09-18

### Added
- Akış halinde export. 100 MB üzeri dosyalar artık zaman
  aşımına uğramıyor.

### Deprecated
- `legacyAuth()` hâlâ çalışıyor ama 3.0'da kaldırılacak.
  `auth()` kullanın.

[Unreleased]: https://github.com/acme/tool/compare/v2.3.1...HEAD
[2.3.1]: https://github.com/acme/tool/compare/v2.3.0...v2.3.1
[2.3.0]: https://github.com/acme/tool/compare/v2.2.0...v2.3.0

Değerin çoğunu dört ayrıntı taşır. Her versiyonun ISO biçiminde bir tarihi vardır, böylece okuyucu onu sorununun başladığı zamanla eşleştirebilir. Her versiyon başlığı compare görünümüne bir bağlantıdır, böylece tam diff bir tık uzaktadır. Bir düzeltme hangi versiyonun bozduğunu söyler. Ve Security bölümü ayrı durur, böylece “şimdi yükseltmem gerekiyor mu” diye tarayan biri onu saniyeler içinde bulur.

CHANGELOG.md nasıl güncel tutulur?

Satırı değişiklikle aynı pull request’te, Unreleased altına yazın ve release yaparken bölümü bir versiyon başlığına taşıyın. Yöntemin tamamı bu. Dosya, satır daha sonra başka biri tarafından, release zamanında, yazmadığı commit mesajlarının listesinden yazıldığında bayatlar.

Alışkanlığın tutmasını iki şey sağlar. Birincisi, src/’ye dokunup changelog’a dokunmayan bir pull request’i düşüren bir CI kontrolü; kullanıcıya görünür etkisi olmayan değişiklikler için onu atlatan bir etiketle. GitHub Action olarak changelog kontrolü kırk satırlık halini gösterir. İkincisi, Unreleased’i tek komutla versiyon ve tarihe çeviren bir release adımı, böylece kimse bunu elle yapmayı hatırlamak zorunda kalmaz. Changelog’u kim yazar, ekiplerin satırın kimin işi olduğu sorusunu nasıl çözdüğünü anlatır.

Changelog commit’lerden üretilmeli mi?

Üretim size eksiksiz bir taslak verir; bir changelog vermez. Conventional commits üzerine kurulu araçlar ve release-please gibi release otomasyonu, feat:, fix: ve BREAKING CHANGE: öneklerini okur ve her pull request’in bağlantılı olduğu gruplanmış bir liste üretir. Liste ancak commit konuları kadar iyidir ve commit konuları kodu anlatır.

İşe yarayan orta yol, üretip sonra düzenlemektir. Aracın Unreleased bölümünü commit’lerden oluşturmasına izin verin ve release pull request’inin bir kullanıcının okuyacağı satırları yeniden yazmasını sağlayın: fonksiyon adı yerine belirti, değişen dosya yerine yer değiştiren ayar. Conventional commit’lerden changelog’a pipeline’ı adım adım anlatır ve tarayıcıda çalışan bir changelog generator, yapıştırılmış bir git log’dan hiçbir şey kurmadan taslak almaya yeter.

CHANGELOG.md’ye ne girmemeli?

Dahili refactor’lar, davranış değişikliği olmayan bağımlılık güncellemeleri, yalnızca test commit’leri, CI yapılandırması ve biçimlendirme değişiklikleri. Bunlar git geçmişine aittir; ihtiyaç duyan herkes onları orada bulabilir. Onları eklemek önemli satırları gömer ve okuyucuları dosyayı atlamaya alıştırır.

Dışarıda bırakılacak diğer şey, bir değişikliğin pazarlama versiyonudur. “Işık hızında export” okuyucuya kontrol edebileceği hiçbir şey söylemez. “Export artık akış halinde çalışıyor; 100 MB üzeri dosyalar zaman aşımına uğramıyor” söyler. Dosya bir referans belgesidir ve tonu buna uymalıdır: kısa satırlar, somut isimler, her şeyin üstünde bir versiyon ya da tarih. Keep a Changelog, uygulanmış hali spesifikasyonun ekiplerin en sık düşürdüğü kısımlarını, changelog dosya formatları ise Markdown dosyasının yanındaki bir JSON ya da YAML kaynağının ne zaman hak ettiğini anlatır.

Changelog sayfası olan bir ürünün dosyaya hâlâ ihtiyacı var mı?

Bir kütüphanenin var, çünkü paket kayıtlarının gösterdiği ve bir geliştiricinin çevrimdışı okuduğu şey dosyadır. Kurulabilir bir varlığı olmayan bir SaaS ürünü yalnızca sayfayla idare edebilir, çünkü kullanıcıları depoyu hiç görmez. Birçok ekip ikisini de yürütür: dosya mühendislik kaydı olarak, ondan daha geniş bir kitle için yazılan herkese açık bir changelog sayfası ile; ayrıntı changelog vs release notes yazısının anlattığı gibi bölünür. Sayfa dosyadan besleniyorsa, dosyayı gerçeğin kaynağı olarak tutun ve sayfayı üretin, böylece düzenlenecek tek yer olur.

FAQ

CHANGELOG.md ile release notes arasındaki fark nedir? Changelog, her kayda değer değişikliğin depoda tutulan eksiksiz ve sürekli kaydıdır. Release notes tek bir release hakkında bir mesajdır, çoğu zaman daha kısa ve daha geniş bir kitle için yeniden yazılmıştır. Birçok proje bir versiyonun changelog bölümünü release notes olarak yayımlar.

CHANGELOG.md nerede yaşamalı? Depo kökünde, tam o adla; böylece GitHub, paket kayıtları ve release araçları onu bulur. Bir monorepo, paket başına bir tane tutar, her paketin kendi manifest’inin yanında.

CHANGELOG.md’yi git commit’lerinden üretmeli miyim? Taslağı üretin, sonra kullanıcının okuyacağı satırları düzenleyin. Commit mesajları kod değişikliğini anlatır; changelog kullanıcının fark ettiğini anlatır. conventional-changelog ve release-please gibi araçlar iyi bir başlangıç noktası verir.

Her commit bir changelog girdisi gerektirir mi? Hayır. Yalnızca projenin bir kullanıcısının fark edebileceği değişiklikler: yeni yetenek, değişen davranış, deprecation’lar, kaldırmalar, düzeltmeler ve güvenlik yamaları. Refactor’lar, test değişiklikleri ve CI düzenlemeleri git geçmişinde kalır.

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, Changelog örnekleri