Changelog'u kim yazar, kim yazmalı

Bir ekibe changelog’u kimin yazdığını sorun ve dürüst cevap genellikle “kim hatırlarsa” olur, ki bu CI’da bir changelog kaydını zorunlu kılmak’ın mekanik seviyede düzeltmek için var olduğu aynı başarısızlık modudur. Ama bir kaydın var olmasını zorlamak, kimin onu iyi yazmak için nitelikli olduğuna karar vermez, ve bu soruyu atlayan ekipler genellikle zorlaması en kolay olana, genellikle PR yazarına, bunun gerçekten onu iyi yazabilecek kişi olup olmadığını kontrol etmeden varsayılan olarak yönelir.

PR yazarı neden otomatik olarak en iyi changelog yazarı olmuyor?

Çünkü uygulamayı bilir, illa etkiyi değil, ve bunlar farklı bilgi türleridir. Conventional commits nerede durur, bu boşluğu commit mesajı tarafından ele alır: fix(auth): reject expired refresh tokens doğrudur ve bir müşteriye hiçbir şey söylemez, ve o düzeltmeyi yazan kişi genellikle onu çevirmek için en az donanımlı kişidir, çünkü saatlerdir hata açısından düşünmüştür ve bir kullanıcının gerçekte ne yaşadığına dair dışarıdan görüşü kaybetmiştir. Bu, teknik yazarlığın bir meslek olarak var olmasının aynı nedenidir: uygulamayı etkiye çevirmek, o şeyi inşa etmiş olmaktan farklı bir beceridir, ve mühendis kodda ne kadar iyi olursa olsun pratik gerektirir.

Bu, ürün veya destek ekibinin her kaydı onun yerine yazması gerektiği anlamına mı gelir?

Hayır, çünkü onların ters bir boşluğu vardır: kullanıcılar için neyin önemli olduğunu bilirler ama her zaman gerçekte neyin gönderildiğini bilmezler, ki bu okunabilir ama kapsamda arada sırada yanlış kayıtlar üretir, hâlâ bir flag’in arkasında olan bir özellik için “artık X’i destekliyor” iddiası, veya üç durumdan sadece birini kapsarken tam olarak tarif edilen bir düzeltme. Mühendis-yazılı kayıtların başarısızlık modu okunamaz-ama-doğru’dur; PM-yazılı kayıtların başarısızlık modu okunabilir-ama-doğrulanmamış’tır. Hiçbir rol, iyi bir kaydın ihtiyaç duyduğu iki yarının ikisine de sahip değildir.

Çalışan bir sahiplik modeli gerçekte neye benziyor?

Değişikliğe en yakın olandan bir taslak, kullanıcıya en yakın olan tarafından incelenmiş, herkesin başka birinin sorunları yakalayacağını varsaymak yerine son ifadeden sorumlu isimlendirilmiş bir kişiyle. Taslağın iyi olmaktan çok var olması ve doğru olması gerekir; neyin değiştiğini doğru söyleyen mühendis-yazılı kaba bir cümle, cilalı ama doğrulanmamış bir cümleden daha iyi bir başlangıç noktasıdır, çünkü netlik için yeniden yazmak doğruluk için yeniden yazmaktan daha kolaydır. İnceleme adımı, bir PM veya destek liderinin taslağı okuyup okunabilirlik boşluğunu yakalayan tek soruyu sorduğu yerdir: kodu görmeseydim bunu anlar mıydım.

Sorumlu kişi her zaman aynı mı olmalı, yoksa rotasyon mu olmalı?

En azından son onay için isimlendirilmiş ve sabit, rotasyona kıyasla kazanır. Rotasyonlu bir sahip, her kaydın ekibin geleneklerini sıfırdan yeniden türeten biri tarafından incelendiği anlamına gelir, ki bu tam olarak sesin kayıttan kayda kaymasının ve bir okuyucunun changelog’un bir komite tarafından yazıldığını fark etmeye başlamasının yoludur. Tek bir kişi, veya çok küçük sabit bir grup, zamanla yargı çağrılarını biriktirir, ne zaman “iyileştirildi” demek ne zaman belirli sayıyı adlandırmak arasında, ne zaman bir düzeltmenin kendi kaydına ihtiyaç duyduğu ne zaman bir grupla katlanacağı arasında, ve o yargı işi eşit dağıtmaktan daha değerlidir.

Taslak (mühendis, PR'dan):
"Fixed pagination cursor not respecting the `sort` param
in some edge cases."

İncelendi (changelog sahibi, gerçek PR'a karşı kontrol edildi):
"Düzeltildi: tarihe göre sıralanan export'lar ilk sayfanın
ötesinde sırasız sonuçlar döndürebiliyordu. Artık tüm
sayfalarda tutarlı."

Küçük bir ekip bir satır metin için bu kadar sürece ihtiyaç duyar mı?

Ayrı kişiler olarak roller değil, ama iki adım tek başına bile hâlâ önemlidir. Bir kişilik bir ekip hem mühendis hem de incelemecidir, ve bu ölçekte hayatta kalan disiplin, incelemeyi ayrı bir zihinsel geçiş olarak yapmaktır, düzeltmeyi yazmaktan onu aynı nefeste yayımlamaya doğrudan atlamak değildir. Küçük ölçekteki tuzak, ikinci bir kişinin eksikliği değil, hiçbir dış güç zorlamadığı için ikinci geçişi tamamen atlamaktır, ve o geçişin yakalamak için var olduğu doğruluk boşluğu, aynı kişinin teorik olarak kendi kör noktasını fark edebileceği için ortadan kalkmaz.

Son kayıttan kimse sorumlu olmadığında ne olur?

Changelog tamamen başarısız olmak yerine düzensiz şekilde bozulur, ki bu daha kötüdür çünkü bir okuyucu bunu işaret edene kadar kimse fark etmez. Bazı kayıtlar keskin kalır çünkü onları yazan kişi umursamıştır; diğerleri belirsizleşir, “çeşitli iyileştirmeler ve hata düzeltmeleri”, çünkü onları yazan kişi hızlı hareket ediyordu ve kimse yayımlanmadan önce bunu yakalamadı. Keep a Changelog’ın format kısıtlamaları yapısal kaymayı yakalar, eksik tarihler, yanlış kategoriler, ama hiçbir şablon teknik olarak iyi biçimlendirilmiş belirsiz bir kaydı yakalamaz, ki bu tam olarak isimlendirilmiş bir sahibin kapatmak için orada olduğu boşluktur.

FAQ

Changelog sahibi bir mühendislik mi yoksa ürün rolü mü olmalı? Kişi hem kapsamı doğrulamak için teknik akıcılığa hem de dışarıdan bir okuyucu için yazacak kadar uygulamadan mesafeye sahipse ikisi de işe yarayabilir; unvan, ikisini de yapıp yapamadığından, veya yapamadığı yarı için kime sorması gerektiğini bilip bilmediğinden daha az önemlidir.

Changelog sahipliği için rotasyonlu bir nöbetçi tarzı program hiç uygun mudur? Hacim için bazen, ekip bir kişinin her şeyi incelemesi için çok küçükse; ses ve yargı için hayır, çünkü rotasyonun aşındırdığı tam olarak budur. Yazma yükünü paylaşırken sabit bir incelemeciyi koruyan bir rotasyon, kaymadan faydayı elde eder.

Mevcut sahiplik yapısında bir şeylerin yanlış olduğunun en hızlı işareti nedir? Kim yazdığını izleyen bir kalıpta, doğru ama okunamaz, veya okunabilir ama kapsamda yanlış kayıtlar. Kalite tutarlı kalmak yerine yazarla ilişkiliyse, boşluk sahipliktir, yazma becerisi değildir.

Otomasyon sahipliğin ne kadar önemli olduğunu azaltır mı? Ne kadar yazmaya ihtiyaç olduğunu azaltır, ne kadar yargıya ihtiyaç olduğunu değil. Changelog otomasyonu, bir pipeline’ın güvenle üretebileceklerini ele alır, biçimlendirme, yayınlama, çapraz gönderim; ifade, gruplandırma ve bahsetmeye değer sayılan şey, pipeline’ın ne kadarı otomatikleştirilmiş olursa olsun insan kararları olarak kalır.

PR yazarı ile inceleyen kişi ifade konusunda anlaşamazsa ne olur? Karar inceleyen kişiye aittir, çünkü cevapladığı soru, dışarıdan bir okuyucu bunu anlar mıydı, rolün korumak için var olduğu sorudur. Bu, mühendisin okumasını değersiz kılmaz: anlaşmazlık ifadeden çok doğruluk hakkındaysa, inceleyen kişi geri çekilir, çünkü kapsamı doğru almak yazarın yarısıdır. İki tür anlaşmazlığı, ifade ile doğruluk, ayırmak bunların çoğunun çıkmaza dönüşmesini engeller.

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