Changelog otomasyonu, ve sınırları

Changelog otomasyonu, toplama, sınıflandırma ve yayımlamayı otomatikleştirdiğinde işe yarar, ve seçim ile ifadede durur. Her şeyi otomatikleştirin ve biçimlendirilmiş bir git log gönderirsiniz; hiçbirini otomatikleştirmeyin ve changelog sürümlerden önce, hafızadan, ani atılımlarla yazılır. Faydalı soru hangi kısımları otomatikleştireceğinizdir, ne kadarını değil.

Changelog otomasyon projeleri iki yönden birinde başarısız olur, ve her ikisi de ilk tasarım toplantısından tahmin edilebilir. Çok az otomatikleştirin ve changelog birinin güncellemesi gereken bir belge haline gelir, ki bu kısa çöp çekeni kim aldıysa onun tarafından ani atılımlarla güncellendiği anlamına gelir. Çok fazla otomatikleştirin ve biçimlendirilmiş bir git log haline gelir: eksiksiz, doğru, ve kimsenin okumadığı.

Bir changelog’un hangi kısımları otomatikleştirilmeli?

Dört adımdan üçü. Toplama ve yayımlama tamamen; sınıflandırma insan müdahalesiyle ilk geçiş olarak; seçim ve ifade asla.

Toplama. Değişiklikleri gerçekleştikleri yerden (commit’ler, PR’lar, ticket’lar) alıp bir listeye koymak. Bunu tamamen otomatikleştirin. İnsanlar bunda kötüdür, sıkıcıdır, ve son tarih altında atlanan adımdır. Conventional commits veya PR etiketleri genellikle ham malzemedir.

Sınıflandırma. Bir şeyin Added, Fixed, Changed, Deprecated, Removed veya Security olup olmadığına karar vermek. Commit türünden veya PR etiketinden ilk geçişi otomatikleştirin, ve bir insanın geçersiz kılmasına izin verin. Buradaki doğruluk sadece metadata’dan yaklaşık yüzde seksendir, ve yanlış yüzde yirmi tam olarak önemli olan girdilerde yoğunlaşır, çünkü belirsizlik önemle korelasyon gösterir.

Seçim ve ifade. Bir okuyucuya ne söylenmesi gerektiğine ve nasıl söyleneceğine karar vermek. Bunu otomatikleştirmeyin. Artefaktın tüm değeri budur. Geri kalan her şey lojistiktir.

Yayımlama. Tamamlanmış girdileri bir sayfaya, bir akışa, bir e-postaya, uygulama içi bir widget’a, bir Slack kanalına götürmek. Tamamen, ve tek bir kaynaktan otomatikleştirin. Çoğu manuel çabanın gerçekte gittiği yer burasıdır, ve neredeyse kimse bunu saymaz. Aynı zamanda değişikliği isteyen kişiye gönderildiğini söyleyebilen adımdır, ki bu geri bildirim döngüsünü changelog tarafından kapatmak’ın tamamıdır. E-posta yarısının, ürün güncellemesi e-posta şablonu’nda kendi biçimi var.

Son nokta üzerinde durmaya değer. Ekipler changelog’u bir yazma sorunu olarak görme eğilimindedir, ve sonra çoğu zamanı dağıtıma harcarlar: girdileri bir e-posta aracına kopyalamak, uygulama içi için yeniden biçimlendirmek, Slack’e yapıştırmak, bir doküman sayfasını güncellemek. Yazmak bir saat sürer. Kopyalamak her sürüm için bir saat sürer, sonsuza dek, ve bu bir makinenin sahip olması gereken kısımdır.

Çizgi kaydığında ne olur?

Yukarı kaydırın ve bir git dump’ı alırsınız. Commit’lerden tam otomasyon, müşterilerin önünde bump deps, fix flaky test, wip ve address review comments üretir. Bunu yapan her ekip sonrasında bir filtre eklemiştir, ve filtre başka bir isim altında yeniden tanıtılmış, daha kötü ergonomiye sahip bir seçim adımıdır.

Aşağı kaydırın ve ani atılımlar alırsınız. Tamamen manuel toplama, girdilerin sürüm zamanında hafızadan yazıldığı anlamına gelir. Bu, Keep a Changelog’un en başta uyardığı moddur, ve sessizce bozulur: changelog, kimsenin vakti olmadığı haftaya kadar bakımlı görünür.

Bir changelog otomasyon pipeline’ı nasıl görünür?

Bir taslağın halka açık hale geldiği yere yerleştirilmiş tam olarak bir insan kapısı ile dört adım.

1. Merge’de, PR’dan bir taslak girdi türetin: etiketten veya commit önekinden tür, ilk taslak olarak başlık, PR’a geri bağlantı, kaydedilen yazar. Yayımlanmamış bir kovaya yerleştirin.
2. Herkes herhangi bir zamanda herhangi bir taslağı düzenleyebilir, ve düzenlemek ucuzdur. Çoğu bir satırlık yeniden yazım alır.
3. Bir sürüm kesmek, kovadaki her girdinin ya düzenlenmiş ya da açıkça dahili olarak işaretlenmiş olmasını gerektirir. Bu kapı tüm tasarımdır. Onsuz, taslaklar meşgul haftada düzenlenmemiş olarak gönderilir.
4. Yayımlamak, yayımlanmış setten bir fan-out’tur: genel sayfa, akış, e-posta, widget, Slack gönderisi. Tek kaynak, birden çok görselleştirme, kopyalama yok.

Adım 3, bir insanın gerekli olduğu tek yerdir, ve taslaklar makul olduğunda sürüm başına yaklaşık on dakika sürer. Bir müşteri talebinin dahil olduğu yerde, taslak ayrıca kapattığı issue’yu taşır, ki bu adım 4’ün talep edeni bilgilendirmesini sağlayan şeydir; feature-request-şablonu bu bağlantının hayatta kalması için tasarlanmıştır. Bu adımın daha geniş release akışında nerede durduğu release yönetimi süreci yazısının konusudur.

Otomasyon verilerinizden ne gerektirir?

Yukarıdakilerin hiçbiri, changelog bir Markdown dosyasıysa çalışmaz, çünkü bir dosya yeniden parse edilmeden beş yüzeye görselleştirilemez, ve düz yazıyı parse etmek yarım bir başlık gösteren bir widget’la sonuçlanmanızın yoludur.

Girdilerin yapılandırılmış olması gerekir: bir tür, bir tarih, bir sürüm veya sürüm tanımlayıcısı, bir hedef kitle, bir gövde ve bir bağlantı. O zaman dosya, sayfa, akış ve e-posta hepsi görünümlerdir. Bu yapısal nokta, bir araç seçmeden önce doğru yapmaya değer olan tek şeydir, çünkü bu ucuza sonradan ekleyemeyeceğiniz şeydir. Bunların hiçbiri, ihtiyaç duyan her değişiklik için gerçekten bir kayıt oluşturulmadıkça çalışmaz; CI’da bir changelog kaydını zorunlu kılmak bu adımı hafızaya bırakmak yerine pipeline’ın kayıtsız merge’ü nasıl reddedeceğini ele alır.

Changelog’un önce bir akış sonra bir sayfa olduğu changeloop’u inşa ediyoruz, bu yüzden bunu tarafsız bir öneri yerine bir çıkar olarak okuyun; fiyatlandırma kartsız bir ücretsiz repository’dir, şekli görmeye yeterlidir. Changelog araçları rakip olduğumuz ürünler dahil, başka ne olduğunun özetimizdir, ve changelog üreticisi bir pipeline’a bağlanmadan önce türetmeyi görmek isterseniz toplama ve sınıflandırma adımlarını tarayıcıda yapar.

Test

Bir değişikliğin merge edilmesi ile o değişikliğin repo’nuzu okumayan bir müşteri için görünür olması arasındaki dakikaları sayın. Bu dakikaların çoğu birinin araçlar arasında metin kopyalamasıysa, ihtiyacınız olan otomasyon yazmada değil yayımlamadadır.

FAQ

Yapay zeka changelog’u yazabilir mi? Bir taslak hazırlayabilir. Merge edilmiş pull request’i verilen bir model çoğunlukla başlık ve gövdenin kullanılabilir bir ilk taslağını üretir, ki bu toplama ve sınıflandırma adımlarının daha iyi yapılmasıdır. Seçim, bir okuyucuya bir şey söylenip söylenmemesi gerektiği, ve son ifade hâlâ hedef kitleyi bilen kişiye ihtiyaç duyar, ve o kapı olmadan taslak yayımlayan bir pipeline yanlış adımı otomatikleştirmiştir.

Bir changelog üreticisi ile changelog otomasyonu arasındaki fark nedir? Bir üretici commit’leri talep üzerine bir kez biçimlendirilmiş bir listeye dönüştürür. Otomasyon her merge’de çalışır, yayımlanmamış bir kova tutar, sürümü insan incelemesine bağlar, ve tek bir kaynaktan her yüzeye yayımlar. Üretici, elle çalıştırılan pipeline’ın ilk adımıdır.

Changelog commit’lerden mi yoksa pull request’lerden mi otomatikleştirilmeli? Değişim biriminin PR olduğu pull request’lerden: başlık ve açıklama tüm değişiklik için bir kez yazılır, ve PR kapattığı issue’yu bağlar. Commit tabanlı türetim, commit birim olduğunda ve bir konvansiyonu takip ettiğinde işe yarar.

Otomasyonun dahili değişiklikleri yayımlaması nasıl önlenir? chore, ci, test, refactor ve bağımlılık güncellemelerini varsayılan olarak dahili sınıflandırın, ve genele terfiyi bilinçli bir eylem yapın. Kimse gizlemedikçe genel olan ters varsayılan, bump depsin müşterilere nasıl ulaştığıdı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 araçları karşılaştırması, Changelog oluşturucu