Changelog vs release notes: apa bedanya?

Changelog adalah catatan berkelanjutan dan kumulatif dari semua yang berubah, ditulis untuk seseorang yang sedang mencari sesuatu. Release notes adalah pesan terkurasi tentang satu rilis, ditulis untuk seseorang yang memutuskan apakah itu penting baginya. Perbedaannya ada pada audiens, bukan format, dan kebanyakan tim membutuhkan keduanya: satu sebagai referensi, satu sebagai pengumuman, diturunkan dari entri yang sama.

Kebanyakan tim berakhir dengan salah satunya secara tidak sengaja dan yang lain atas permintaan. Anda mulai dengan changelog karena seorang developer ingin catatan tentang apa yang dirilis. Berbulan-bulan kemudian seseorang dari dukungan bertanya mengapa pelanggan tidak tahu tentang fitur yang sudah aktif sejak April, dan sekarang Anda butuh release notes.

Changelog vs release notes, berdampingan

Apa itu changelog?

Changelog adalah catatan kronologis, hampir lengkap, tentang apa yang berubah, terbaru dulu, dengan setiap entri diberi jenis (added, changed, deprecated, removed, fixed, security) dan tanggal. Pembacanya sudah memutuskan bahwa mereka peduli. Mereka sedang mencari sesuatu: kapan sebuah perilaku berubah, apakah sebuah bug sudah diperbaiki, versi mana yang memperkenalkan flag. Kelengkapan adalah seluruh nilainya, itulah mengapa konvensi Keep a Changelog menghabiskan sebagian besar satu halamannya untuk struktur dan hampir tidak ada untuk prosa.

Apa itu release notes?

Release notes adalah pesan selektif, ditulis dalam prosa, tentang satu rilis. Pembacanya belum memutuskan apa pun. Mereka sedang memutuskan apakah rilis ini penting bagi mereka, dan apakah mereka harus melakukan sesuatu tentang itu. Seleksi adalah seluruh nilainya: release note yang mendaftar semuanya adalah changelog dengan paragraf, dan mengecewakan pembaca dengan cara yang sama seperti changelog yang melewatkan sesuatu mengecewakan pembacanya. Cara menulis release notes membahas tentang seleksi dan formulasi.

Apakah Anda membutuhkan changelog dan release notes?

Anda membutuhkan keduanya begitu kedua audiens Anda menginginkan hal yang berbeda; sebelum itu, satu artefak yang melakukan kedua tugas adalah benar. Tim kecil menerbitkan satu halaman /changelog dengan paragraf singkat di atas setiap entri, dan untuk sementara itu melayani baik developer yang mencari perbaikan maupun pelanggan yang sekilas mencari berita. Membagi terlalu dini memberi Anda dua hal untuk dipelihara dan salah satunya akan membusuk.

Pembagian menjadi layak ketika ini mulai terjadi:

• Entri changelog Anda telah berkembang menjadi paragraf penjelasan yang dilewati developer.
• Atau sebaliknya: pengumuman rilis Anda mulai mendaftar pembaruan dependensi.
• Dukungan menyalin entri ke email dan menulis ulang di tengah jalan.
• Seseorang meminta “hanya breaking change” dan Anda tidak bisa memfilternya.

Yang terakhir itu tanda sebenarnya. Jika tidak ada yang bisa menjawab “apa yang berubah yang memengaruhi saya” tanpa membaca semuanya, Anda punya satu artefak yang melakukan dua tugas dengan buruk.

Satu sumber, dua tampilan

Kesalahannya adalah memperlakukan keduanya sebagai dua dokumen. Keduanya adalah dua tampilan atas kumpulan perubahan yang sama.

Tulis changelog seiring waktu, satu entri per perubahan yang berarti, masing-masing diberi label apa itu: fixed, added, changed, removed, deprecated, security. Jaga entri cukup singkat sehingga menulis satu bukan keputusan besar. Kemudian, saat rilis, release notes adalah seleksi dan penulisan ulang: ambil entri yang penting bagi manusia, kelompokkan berdasarkan apa yang memungkinkan seseorang lakukan, dan letakkan alasannya di atas.

Ini punya konsekuensi praktis. Jika changelog adalah sumbernya, ia perlu menjadi data terstruktur, bukan halaman yang dikelola manual. Sebuah entri butuh jenis, tanggal, versi, dan cara menyatakan untuk siapa itu. Begitu punya itu, halaman publik, widget in-app dan feed RSS atau JSON adalah tiga rendering dari satu hal, dan tidak ada yang menulis ulang apa pun di tengah jalan menuju pelanggan. Email release notes bisa mengutip entri yang sama, dari alat apa pun yang mengirim email Anda. Otomatisasi changelog membahas mana dari langkah-langkah ini yang seharusnya dimiliki mesin. Itulah seluruh argumen untuk memperlakukan changelog sebagai feed daripada halaman. Ini juga, secara transparan, apa yang kami bangun, jadi bacalah ini sebagai kepentingan daripada survei netral.

Jika Anda hanya punya waktu untuk satu

Tulis changelog. Lebih murah per entri, berguna di hari Anda menulisnya, dan release notes bisa diturunkan darinya kemudian. Sebaliknya tidak benar: Anda tidak bisa merekonstruksi setahun perubahan dari dua belas email pengumuman, dan orang akan memintanya dari Anda.

Simpan dalam format tetap sehingga penurunan tetap mungkin. Halaman contoh changelog kami mengumpulkan entri dari tim yang melakukan ini dengan baik, dan template release notes adalah bentuk yang kami gunakan saat mengubah sekumpulan entri menjadi sesuatu yang layak dikirim.

Catatan tentang penamaan

Tidak ada yang distandardisasi dari semua ini, dan Anda akan menemukan “release notes” digunakan untuk daftar berkelanjutan dan “changelog” digunakan untuk pengumuman triwulanan. Berdebat tentang kata-katanya tidak sepadan. Putuskan tugas mana dari keduanya yang dilakukan setiap artefak Anda, namai sesuai apa yang sudah dipanggil tim Anda, dan pastikan tidak ada satu pun yang diam-diam melakukan keduanya.

Di permukaan mana hasilnya berakhir adalah keputusan terpisah, dibahas di cara membangun halaman changelog.

FAQ

Apakah changelog sama dengan release notes? Tidak. Changelog adalah catatan lengkap, dibaca oleh yang mencari sesuatu; release notes adalah pengumuman terpilih, dibaca oleh yang memutuskan apakah mereka peduli. Perubahan yang sama muncul di keduanya, diformulasikan berbeda untuk setiap pembaca.

Bisakah release notes dihasilkan dari changelog? Ya, dan itu arah yang benar. Pilih entri yang penting bagi manusia, kelompokkan berdasarkan hasil, tulis ulang judulnya. Sebaliknya, merekonstruksi changelog dari pengumuman, kehilangan semua yang dilewatkan pengumuman.

Di mana changelog seharusnya berada? Di suatu tempat permanen dan bisa ditautkan yang bisa dicapai pembaca tanpa repositori: halaman /changelog, situs dokumen, atau feed yang dirender di beberapa tempat. CHANGELOG.md sendiri menjangkau kontributor, bukan pelanggan.

Haruskah changelog mencakup perubahan internal? Ya, di bawah, satu baris masing-masing. Changelog adalah catatan lengkap. Release notes juga bisa menyimpannya, di bagian terakhir yang singkat, asalkan perubahan yang akan diperhatikan pembaca muncul lebih dulu.

Klaim teknis dalam artikel ini belum ditinjau secara independen. Jika ada yang keliru, beri tahu kami dan kami akan memperbaikinya.

Terkait di changeloop: Contoh changelog, Templat catatan rilis