Monorepo changelog'ları: tek mi, paket başına mı?

Bir monorepo, tek bir repository içinde ayrı ayrı deploy edilen birkaç şeyi barındırır, ve bir changelog önce bir soruyu yanıtlamalıdır: okuyucu repo’yu mu önemsiyor, yoksa içindeki belirli bir paketi mi? Çoğu ekip buna hiç bilinçli olarak karar vermez. Tek bir repo olduğu için tek bir changelog’la başlarlar, zaman içinde paket ekler, ve CLI kullanan birinin kendi düzeltmesini gönderen girişi bulmak için kırk ilgisiz backend girişini geçmesi gereken bir log ile sonuçlanırlar. Doğru şekli belirleyen repository’nin yapısı değil, log’u kimin okuduğu ve zaten neyi aradığını bilmesidir.

Bir monorepo’nun changelog’unu tek bir repo’dan farklı kılan nedir?

Tek repo changelog’unun örtük bir okuyucu kitlesi vardır: o repo’nun inşa ettiği tek şeyi kullanan herkes. Bir monorepo’nun okuyucu kitlesi paket bazında bölünür, ve aynı repo’daki paketler sık sık farklı takvimlerde, farklı tüketicilere, farklı kararlılık seviyelerinde yayınlanır. Bir kayıt defterinde yayınlanan bir kütüphane ile dahili bir yönetim aracı aynı monorepo’da yaşayabilir ve changelog’u okuyan biri için neredeyse hiçbir ortak noktaları olmayabilir.

Her paketin kendi changelog’una ihtiyacı var mı?

Sadece bağımsız bir okuyucu kitlesi olanların. Bir kayıt defterinde yayınlanan bir paket kendi log’una ihtiyaç duyar, çünkü onu kuran kişinin repo’da başka bir şey okumak için hiçbir nedeni yoktur, ve Lerna ve Changesets gibi monorepo sürüm araçları her paket için package.json’ının yanına bir CHANGELOG.md yazar. Aynı repo’da zaten yaşayan uygulamayı tek tüketicisi olan dahili bir yardımcı programın ayrı bir log’a ihtiyacı yoktur; değişikliklerini o uygulamanın girişlerine dahil etmek, ekip dışında kimsenin açmadığı ikinci bir dosyadan daha kullanışlıdır.

Test, herhangi bir girişin bir changelog’a ait olup olmadığına karar verenle aynıdır: okuyucu bunu fark eder mi veya önemser mi, ve bunu bilerek harekete geçebilir mi. Bunu klasöre değil pakete göre uygula, ve on iki paketli bir repo, iki gerçek changelog’la ve buna hiç ihtiyacı olmayan on paketle sonuçlanabilir.

Hangi paketin hangi changelog girişine neden olduğu nasıl bilinir?

Her girişi, bir commit’in hangi dosyaları etkilediğini sonradan inceleyerek değil, giriş yazıldığı anda paketiyle etiketle. Paylaşılan dahili bir kütüphaneyi düzelten bir commit, ona bağımlı olan her pakette bir changelog girişi üretebilir, ve dosya yolları tek başına bu alt akış girişlerinden hangisinin okuyucunun gerçekten görmesi gerektiğini söyleyemez; sadece “bu, A paketini kullanana görünür ve B paketini kullanana görünmez” diye karar veren bir kişi bunu yapabilir. Conventional commits her commit’te paketi adlandırarak burada mekanik olarak yardımcı olur, ama scope yine de sadece bir taslak üretir. O yazının aynı iki katmanlı kuralı paket bazında geçerlidir: doğru scope’a sahip bir taslak, o paketin gerçek okuyucusu için ifade edilmeden önce yine de insan eliyle bir geçiş gerektirir.

Paylaşılan bir changelog, tek repo changelog’unun ihtiyaç duymadığı neye ihtiyaç duyar?

Her girişte, açıklamadan önce, en başta bir paket etiketi, böylece log’a göz atan bir okuyucu tek bir geçişte kendisine ait olmayan her şeyi atlayabilir. Bu etiket olmadan, paylaşılan bir log rastgele bir akış gibi okunur, ve bir pakete ilgi duyan bir okuyucu, hangi satırların önemli olduğunu ezberlemek dışında onu filtrelemenin bir yolunu bulamaz, ki bunu ilk haftadan sonra kimse yapmaz.

## 2026-09-07

### [cli] Eklendi
- `acme push --dry-run` gerçekten göndermeden neyin
  gönderileceğini gösterir.

### [core] Düzeltildi
- Yeniden deneme geri çekilmesi artık boş gövde döndüren başarılı
  bir istekte sıfırlanmıyor.

İki giriş, iki okuyucu kitlesi, ayırt etmek için tek bakış. Changesets tarzı bir iş akışı bu etiketlemeyi doğrudan release sürecine gömer: katkıda bulunan biri değişikliğinin yanında pakete özel kısa bir not yazar, ve araç, birleştirilmiş bir commit geçmişinden geriye dönük paket sınırlarını yeniden inşa etmeye çalışmak yerine, release anında bu notlardan paket başına changelog’lar ve versiyon sıçramaları oluşturur.

Versiyonlama bir monorepo changelog’uyla nasıl ilişkilenir?

Bağımsız olarak versiyonlanan paketlerin kendi changelog’una ihtiyacı vardır çünkü kendi versiyon numaraları vardır, ve paylaşılan bir changelog, tek bir dosya içinde iki log’a dönüşmeden “A paketi 2.1’den 2.2’ye geçerken B paketi 1.4’te kaldı” ifadesini veremez. Semantic versioning ve changelog’unuz bir versiyon numarasının changelog kategorilerine nasıl eşlenmesi gerektiğini ele alır; bir monorepo’da bu eşleme paket bazında uygulanmalıdır, çünkü bir pakette bulunan breaking change, ona bağımlı olmayan kardeş bir paket için breaking change değildir.

Bir ürünü, birçok dahili paketten inşa edilmiş olsa bile tek bir deploy edilebilir birim olarak gönderen bir repo bu sorunu yaşamaz: paketler her zaman birlikte release edildikleri için bir versiyonu paylaşırlar, ve tek bir changelog doğrudur.

Git etiketleri bir monorepo’ya nasıl uyar?

Git etiketleri, release’ler ve changelog’unuz yazısındaki aynı kural, paket bazında uygulanarak geçerlidir: kendi versiyonu olan bir paketin kendi etiket önekine ihtiyacı vardır, tipik olarak hangi pakete ait olduğunu söyleyemeyen çıplak bir v1.4.0 yerine paket-adi@1.4.0. Sadece çıplak versiyon numaralarıyla etiketlenmiş bir monorepo, sonradan “cli 2.2’yi gönderdiğinde core’da ne vardı” sorusunu yanıtlayamaz, çünkü diskte hiçbir şey o etiketin gerçekte hangi pakete ait olduğunu kaydetmez.

FAQ

Bir monorepo’daki her paket için ayrı bir changelog’a ihtiyacım var mı? Sadece bağımsız okuyucu kitlesi olan paketler için, genellikle bir kayıt defterinde yayınlanan her şey. Aynı repo’da zaten yaşayan tek bir dahili tüketicisi olan bir paket, kendi log’unu tutmak yerine o tüketicinin log’una dahil olabilir.

Bir changelog girişini doğru paketle ne etiketler? Değişen dosya yollarının otomatik bir taraması değil, girişi yazan kişi, onu yazdığı anda. Paylaşılan bir kütüphanedeki bir değişiklik, ona bağımlı her pakette farklı bir giriş üretebilir, ve sadece bir insan bu alt akış girişlerinin her birinin gerçekte ne söylemesi gerektiğine karar verebilir.

Bir monorepo her şey için tek bir versiyon numarası mı kullanmalı? Sadece her paket her zaman diğerleriyle birlikte release edilirse. Paketler bir gün bağımsız olarak yayınlanırsa, bağımsız versiyonlara ihtiyaç duyarlar, ve bağımsız versiyonların anlamlı olması için bağımsız changelog’lara ihtiyaçları vardır.

Bir monorepo changelog aracı insan düzenleme adımının yerini alır mı? Hayır. Changesets gibi araçlar, release anında pakete özel notları toplama ve birleştirme işini otomatikleştirir; notun kendisi, katkıda bulunanın değil okuyucunun diliyle yazılmış olarak, başka her changelog pipeline’ında olduğu gibi hâlâ bir kişinin işidir.

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