Keep a Changelog, gerçekten uygulandı
4 dk okuma güncellendi:
Keep a Changelog, bir CHANGELOG.md için tek sayfalık bir konvansiyondur: en yeni sürüm önce, bir
numara ve ISO tarihi olan sürüm başına bir bölüm, altı tür (Added, Changed, Deprecated, Removed,
Fixed, Security) altında gruplanmış girdiler, ve sürümler arasındaki girdiler için en üstte bir
Unreleased bölümü. Ondan bahseden çoğu ekip yaklaşık üçte ikisini uygular, ve bıraktıkları üçte
biri kullanıcılarını koruyan üçte birdir.
Olivier Lacan, Keep a Changelog’u 2014’te çoğu yazılım yazısından daha iyi yaşlanmış bir cümleyle yayımladı: don’t let your friends dump git logs into changelogs. On yıl sonra, yazılımın bu köşesinin bir standarda en yakın olduğu şeydir. Bir özet yerine kaynağı okumak değerlidir; bu makale bırakılan kısımlarla ilgilidir.
Keep a Changelog ne ister?
Repo kökünde bir CHANGELOG.md, en yeniden başlayarak, sürüm başına bir bölüm ile. Her sürüm bir
numara ve ISO tarihi taşır, ve girdilerini altı tür altında gruplandırır:
| Tür | Ne için | Bırakmanın maliyeti |
|---|---|---|
| Added | Yeni özellikler | Hiçbir şey; kimse bunu bırakmaz |
| Changed | Mevcut davranıştaki değişiklikler | Okuyucular davranış değişikliğini bir hatadan öğrenir |
| Deprecated | Kaldırılmak üzere olan özellikler | Bir kaldırma, planlı bir olay yerine bir olay haline gelir |
| Removed | Bu sürümde kaldırılan özellikler | Kimse bir kaldırmayı bir hatadan ayıramaz |
| Fixed | Hata düzeltmeleri | Hiçbir şey; kimse bunu da bırakmaz |
| Security | Güvenlik açıkları | Onu arayan tek okuyucu bulamaz |
Artı en üstte bir Unreleased bölümü, böylece bir girdi merge edildiği anda konulacak bir yer
olur, ve herkes neyin geldiğini görebilir.
Bu neredeyse hepsi. Geri kalanı gerekçedir: girdiler insanlar içindir, değişiklik başına bir girdi, ve dosya bir günlük yerine bir belgedir.
Keep a Changelog’un hangi bölümleri bırakılır?
Unreleased bölümü, ardından altı türün dördü, Security de aralarında, bu sırayla.
Unreleased önce ortadan kalkar. Son tarihi olmayan bölümdür, bu yüzden bakımı ilk duran
bölümdür, ve gittiğinde girdiler sürüm zamanında commit geçmişinden yazılır. Bu, spesifikasyonun
en başta uyardığı git-log-dump’ın tam olarak kendisidir, kademeli olarak ulaşılmış.
Changelog otomasyonu çoğunlukla bu bölümü kimsenin hatırlamasına
gerek kalmadan canlı tutmakla ilgilidir.
Altı tür ikiye çöker. Çoğu gerçek changelog Added ve Fixed ile sonuçlanır, çünkü Changed ve Deprecated birinin neye güvendiği hakkında bir yargı gerektirir. Bu yargı değerli olan kısımdır. Deprecated özellikle gelecek hakkında bir söz olan tek türdür, ve onu bırakmak bir kaldırmanın nasıl bir olaya dönüştüğüdür; o sözü tutmanın mekanizması bir API nasıl deprecate edilir içindedir.
Security ayrı olmaktan çıkar. Fixed altında dosyalanmış bir güvenlik düzeltmesi, onu arayan tek okuyucu için görünmezdir. Düzeltme önemsiz olsa bile onu ayrı tutun, ve özellikle ona dikkat çekmeyi tercih etmediğinizde.
Spesifikasyon neyi cevaplamaz?
Bu bir dosya formatıdır. Onu benimsedikten hemen sonra karşılaşacağınız sorular hakkında hiçbir şey söylemez:
- Bunu kim nasıl öğrenir? Bir repo’daki bir dosya katkıda bulunanlara ulaşır. Hiç GitHub açmamış bir müşteriye ulaşmaz.
- Sürümü olmayan ürünler ne olacak? Sürekli dağıtılan bir hizmetin gruplayacak bir v4.2.0’ı yoktur. Çoğu ekip bunun yerine tarihleri kullanır, ki bu işe yarar, ve spesifikasyon bunu ne onaylar ne de yasaklar.
- Girdiyi kim yazar? Spesifikasyon bir insanın yaptığını varsayar. Ne zaman yapacağını söylemez.
- Birden çok hedef kitle ne olacak? Bir dosya geliştiricilere hizmet eder. Aynı içeriği teknik olmayan bir yöneticiye hizmet etmez, ve onun için elle yeniden biçimlendirmek çoğaltmanın başladığı yerdir. Changelog vs release notes spesifikasyonun size kendinize bıraktığı bölünmedir.
Fikrin daha katı bir çatalı olan Common Changelog, bunun bir kısmını sıkılaştırır: belirli girdi ifadelerini yasaklar, değişikliğe bir bağlantı gerektirir, ve okuyucunun kim olduğu konusunda net bir görüşe sahiptir. Keep a Changelog’un gevşek kısımları ekibinizin sürekli tartıştığı şeyse okumaya değer.
Keep a Changelog git loglarını dökmeden otomatikleştirilebilir mi?
Evet: taslağı yapılandırılmış commit’lerden türetin, türü önceden doldurulmuş olarak Unreleased’e koyun, ve bir sürüm kesilmeden önce bir insanın ifadeyi düzenlemesini zorunlu kılın. Spesifikasyonun uyarısı çıktı hakkındadır, araç hakkında değil. Commit’lerden bir taslak türetmek sorun değil. O taslağı düzenlenmemiş olarak yayımlamak karşı çıktığı şeydir.
Makine, iyi olduğu toplama ve biçimlendirmeyi halleder. İnsan, iyi olmadığı seçim ve ifadeyi halleder. Conventional commits, bunun dayandığı iki katmanlı ayrımı ve hangi commit türlerinin yukarıdaki altı kategoriden hangisine karşılık geldiğini anlatır. Changelog araçları özetimiz toplama yarısı için var olanı kapsar.
Keep a Changelog nerede yetersiz kalmaya başlar?
Dağıtımda durur. Keep a Changelog, “bu dosya nasıl görünmeli” sorusuna iyi bir cevaptır. “Kullanıcılarımız neyin değiştiğini nasıl öğrenir” sorusuna bir cevap değildir, çünkü bir repo’daki bir Markdown dosyası, sadece kullanıcılarınız katkıda bulunanlarsa işe yarayan bir dağıtım stratejisidir.
Bu, çoğu ekibin ikinci karşılaştığı engeldir: dosya iyi durumda, ve ekip dışında kimse onu okumuyor. Bunu çözmek, girdilerin başka bir yerde görselleştirilebilecek verilere dönüşmesi anlamına gelir, ki bu bir dosyayı biçimlendirmekten farklı bir sorundur, ve changelog örnekleri’nin repo dosyaları yerine genel changelog sayfaları toplamasının sebebidir. O girdileri insanların geri döndüğü bir şeye dönüştürmek, bir changelog sayfası nasıl kurulur’da ele alınır.
Yine de spesifikasyonu benimseyin. Bir öğleden sonra sürer, ikinci sorunu ele alınabilir hale getirir, ve bu konuda yazılmış hâlâ en iyi tek sayfadır.
FAQ
Keep a Changelog bir standart mı? Geniş bir kabul gören bir konvansiyondur, bir standardizasyon kuruluşunun spesifikasyonu değildir. Araçlar (sürüm scriptleri, linter’lar, parser’lar) şeklini o kadar sık varsayar ki onu takip etmek uyumluluk satın alır.
Unreleased bölümüne ne girer? Merge edilmiş ancak numaralı bir sürümde henüz gönderilmemiş bir değişiklik için her girdi. Bir sürüm kesildiğinde, bölüm sürüm ve tarih olarak yeniden adlandırılır, ve üstüne yeni, boş bir Unreleased bölümü gelir.
Bir changelog semantik versiyonlama kullanmalı mı? Keep a Changelog bunu önerir ve zorunlu kılmaz. Kütüphaneler ve API’ler bundan faydalanır; sürekli dağıtılan bir hizmet genellikle tarihleri kullanır, ki format buna izin verir.
Güvenlik düzeltmeleri kamuya açılmadan önce changelog’da olmalı mı? Girdiyi düzeltme gönderildiğinde ekleyin, bir operatörün harekete geçmesine yetecek kadar detayla, daha fazlasıyla değil. Girdiyi koordine bir açıklama tarihine kadar ertelemek normaldir; onu atlamak değildir.
Bu yazıdaki teknik iddialar bağımsız olarak kontrol edilmedi. Yanlış bir şey varsa bize söyle, düzeltelim.