Changelog vs release notes: fark nedir?

Bir changelog, bir şey arayan biri için yazılmış, değişen her şeyin sürekli, birikimli bir kaydıdır. Release notes ise, onu ilgilendirip ilgilendirmediğine karar veren biri için yazılmış, tek bir sürüm hakkında özenle seçilmiş bir mesajdır. Fark biçimlendirmede değil hedef kitlededir, ve çoğu ekibin ikisine de ihtiyacı vardır: biri referans olarak, biri duyuru olarak, aynı girdilerden türetilmiş.

Çoğu ekip birine kazara diğerine talep üzerine sahip olur. Bir geliştirici neyin yayımlandığının bir kaydını istediği için bir changelog’la başlarsınız. Aylar sonra destekten biri müşterilerin Nisan’dan beri canlı olan bir özelliği neden bilmediğini sorar, ve artık release notes’a ihtiyacınız var.

Changelog vs release notes, yan yana

Bir changelog nedir?

Bir changelog, en yeniden başlayarak, her girdi türlendirilmiş (added, changed, deprecated, removed, fixed, security) ve tarihli, kronolojik, neredeyse eksiksiz bir değişim kaydıdır. Okuyucusu zaten ilgilendiğine karar vermiştir. Bir şey arıyor: bir davranış ne zaman değişti, bir hata düzeltildi mi, hangi sürüm bir flag getirdi. Eksiksizlik tüm değerdir, bu yüzden Keep a Changelog konvansiyonu tek sayfasının çoğunu yapıya harcar ve neredeyse hiçbirini düz yazıya.

Release notes nedir?

Release notes, düz yazı olarak yazılmış, seçici bir mesajdır, tek bir sürüm hakkında. Okuyucusu henüz hiçbir şeye karar vermemiştir. Bu sürümün onu ilgilendirip ilgilendirmediğine, ve bir şey yapması gerekip gerekmediğine karar veriyor. Seçim tüm değerdir: her şeyi listeleyen bir release note, paragraflı bir changelog’dur, ve bir şeyleri atlayan bir changelog okuyucusunu nasıl başarısız kılıyorsa aynı şekilde okuyucusunu başarısız kılar. Release notes nasıl yazılır seçim ve ifadelendirme hakkındadır.

Hem bir changelog’a hem release notes’a ihtiyacınız var mı?

İki hedef kitleniz farklı şeyler istediğinde ikisine de ihtiyacınız var; o zamana kadar iki işi yapan tek bir artefakt doğrudur. Küçük ekipler, her girdinin başında kısa bir paragraf içeren tek bir /changelog sayfası yayımlar, ve bir süre bu bir düzeltme arayan geliştiriciye ve haberleri tarayan bir müşteriye eşit derecede hizmet eder. Çok erken bölmek size sürdürülecek iki şey verir ve ikisinden biri çürür.

Bölünme şu olmaya başladığında değerli hale gelir:

• Changelog girdileriniz geliştiricilerin kaydırıp geçtiği açıklayıcı paragraflara büyümüştür.
• Ya da tam tersi: sürüm duyurularınız bağımlılık güncellemelerini listelemeye başlamıştır.
• Destek girdileri e-postalara kopyalıyor ve yolda yeniden yazıyor.
• Biri “sadece breaking change’ler” istiyor ve onları filtreleyemiyorsunuz.

Sonuncusu gerçek işarettir. Kimse her şeyi okumadan “beni etkileyen ne değişti” diye cevap veremiyorsa, iki işi kötü yapan tek bir artefaktınız var demektir.

Tek bir kaynak, iki görünüm

Hata onları iki belge olarak ele almaktır. Aynı değişiklik kümesinin iki görünümüdür.

Changelog’u ilerledikçe yazın, anlamlı her değişiklik için bir girdi, her biri ne olduğuyla etiketlenmiş: fixed, added, changed, removed, deprecated, security. Girdileri birini yazmanın bir karar olmayacağı kadar kısa tutun. Sonra, sürüm zamanında, release notes bir seçim ve yeniden yazımdır: bir insanı ilgilendiren girdileri alın, birine ne yapmasını sağladıklarına göre gruplandırın, ve nedeni en üste koyun.

Bunun pratik bir sonucu var. Changelog kaynaksa, yapılandırılmış veri olması gerekir, elle tutulan bir sayfa değil. Bir girdinin bir türe, bir tarihe, bir sürüme, ve kim için olduğunu söyleyen bir yola ihtiyacı vardır. Bunu sahip olduğunda, genel sayfa, uygulama içi widget ve RSS veya JSON feed’i tek bir şeyin üç görselleştirmesi olur, ve kimse bir müşteriye giden yolda hiçbir şeyi yeniden yazmaz. Bir release notes e-postası, e-postanızı hangi araç gönderiyorsa oradan aynı girişi alıntılayabilir. Changelog otomasyonu bu adımlardan hangisinin bir makineye ait olması gerektiğiyle ilgilidir. Bu, bir changelog’u sayfa yerine bir akış olarak ele almanın tüm argümanıdır. Aynı zamanda, tam şeffaflıkla, bizim inşa ettiğimiz şeydir, bu yüzden bunu tarafsız bir araştırma yerine bir çıkar olarak okuyun.

Sadece birine vaktiniz varsa

Changelog’u yazın. Girdi başına daha ucuzdur, yazdığınız gün faydalıdır, ve release notes daha sonra ondan türetilebilir. Tersi doğru değildir: on iki duyuru e-postasından bir yıllık değişikliği yeniden oluşturamazsınız, ve insanlar sizden bunu isteyecektir.

Türetmenin mümkün kalması için sabit bir formatta tutun. Changelog örnekleri sayfamız bunu iyi yapan ekiplerin girdilerini toplar, ve release notes şablonu bir girdi setini göndermeye değer bir şeye dönüştürürken kullandığımız formdur.

Adlandırma üzerine bir not

Bunların hiçbiri standardize değildir, ve “release notes”un sürekli bir liste için, “changelog”un üç aylık bir duyuru için kullanıldığını göreceksiniz. Kelimeler hakkında tartışmak buna değmez. İki işten hangisini her artefaktınızın yaptığına karar verin, onu ekibinizin zaten çağırdığı gibi adlandırın, ve ikisinin de sessizce ikisini birden yapmadığından emin olun.

Sonucun hangi yüzeyde bittiği ayrı bir karardır, bir changelog sayfası nasıl kurulur’da ele alınır.

FAQ

Bir changelog release notes ile aynı şey midir? Hayır. Bir changelog, bir şey arayanların okuduğu eksiksiz kayıttır; release notes, ilgilenip ilgilenmeyeceğine karar verenlerin okuduğu seçilmiş duyurudur. Aynı değişiklik ikisinde de görünür, her okuyucu için farklı ifade edilmiş olarak.

Release notes bir changelog’dan oluşturulabilir mi? Evet, ve bu doğru yöndür. Bir insanı ilgilendirecek girdileri seçin, sonuca göre gruplayın, başlığı yeniden yazın. Tersi, bir changelog’u duyurulardan yeniden oluşturmak, duyuruların dışarıda bıraktığı her şeyi kaybeder.

Bir changelog nerede yaşamalı? Okuyucunun bir depoya ihtiyaç duymadan ulaşabileceği kalıcı ve bağlanabilir bir yerde: bir /changelog sayfası, bir doküman sitesi, veya birden çok yerde görselleştirilen bir akış. Tek başına bir CHANGELOG.md katkıda bulunanlara ulaşır, müşterilere değil.

Bir changelog dahili değişiklikleri içermeli mi? Evet, en altta, her biri bir satır. Changelog eksiksiz kayıttır. Release notes da onları kısa bir son bölümde tutabilir, yeter ki okuyucunun fark edeceği değişiklikler önce gelsin.

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 örnekleri, Release notu şablonu