Keep a Changelog, benar-benar diimplementasikan

Keep a Changelog adalah konvensi satu halaman untuk CHANGELOG.md: versi terbaru dulu, satu bagian per versi dengan nomor dan tanggal ISO, entri dikelompokkan di bawah enam jenis (Added, Changed, Deprecated, Removed, Fixed, Security), dan bagian Unreleased di atas untuk entri antar rilis. Kebanyakan tim yang mengutipnya menerapkan sekitar dua pertiganya, dan sepertiga yang mereka lewatkan adalah sepertiga yang melindungi pengguna mereka.

Olivier Lacan menerbitkan Keep a Changelog pada 2014 dengan kalimat yang bertahan lebih baik daripada kebanyakan tulisan perangkat lunak: don’t let your friends dump git logs into changelogs. Sepuluh tahun kemudian, ini adalah hal terdekat dengan standar yang dimiliki sudut perangkat lunak ini. Layak membaca sumbernya daripada ringkasannya; ini membahas bagian-bagian yang dilewatkan.

Apa yang diminta Keep a Changelog?

CHANGELOG.md di root repo, terbaru dulu, dengan satu bagian per versi. Setiap versi membawa nomor dan tanggal ISO, dan mengelompokkan entrinya di bawah enam jenis:

Ditambah bagian Unreleased di atas, sehingga ada tempat untuk meletakkan entri saat merge dilakukan, dan sehingga siapa pun bisa melihat apa yang akan datang.

Itu hampir semuanya. Sisanya adalah alasannya: entri untuk manusia, satu entri per perubahan, dan berkas adalah dokumen alih-alih log.

Bagian mana dari Keep a Changelog yang dilewatkan?

Bagian Unreleased, lalu empat dari enam jenis, Security di antaranya, dalam urutan itu.

Unreleased menghilang lebih dulu. Ini bagian tanpa tenggat waktu, jadi ini yang pemeliharaan-nya berhenti lebih dulu, dan begitu hilang entri ditulis saat rilis dari riwayat commit. Itu tepatnya dump git-log yang diperingatkan spesifikasi sejak awal, dicapai secara bertahap. Otomatisasi changelog sebagian besar tentang menjaga bagian ini tetap hidup tanpa perlu diingat siapa pun.

Enam jenis menyusut jadi dua. Kebanyakan changelog nyata berakhir dengan Added dan Fixed, karena Changed dan Deprecated memerlukan penilaian tentang apa yang diandalkan seseorang. Penilaian itu bagian yang berharga. Deprecated khususnya satu-satunya jenis yang merupakan janji tentang masa depan, dan melewatkannya adalah bagaimana penghapusan berubah menjadi insiden; mekanisme untuk menepati janji itu ada di cara men-deprecate API.

Security berhenti terpisah. Perbaikan keamanan yang diarsipkan di bawah Fixed tidak terlihat bagi satu-satunya pembaca yang mencarinya. Jaga tetap terpisah bahkan ketika perbaikannya sepele, dan terutama ketika Anda lebih memilih tidak menarik perhatian padanya.

Apa yang tidak dijawab spesifikasi?

Ini adalah format berkas. Tidak mengatakan apa-apa tentang pertanyaan yang segera Anda hadapi setelah mengadopsinya:

• Bagaimana seseorang mengetahuinya? Berkas di repo menjangkau kontributor. Tidak menjangkau pelanggan yang tidak pernah membuka GitHub.
• Bagaimana dengan produk tanpa versi? Layanan yang di-deploy terus-menerus tidak punya v4.2.0 untuk dikelompokkan. Kebanyakan tim menggantinya dengan tanggal, yang berhasil, dan spesifikasi tidak merestui atau melarangnya.
• Siapa yang menulis entrinya? Spesifikasi mengasumsikan manusia yang melakukannya. Tidak mengatakan kapan.
• Bagaimana dengan banyak audiens? Satu berkas melayani developer. Tidak melayani konten yang sama kepada admin non-teknis, dan memformat ulang secara manual untuk mereka adalah tempat duplikasi dimulai. Changelog vs release notes adalah pembagian yang dibiarkan spesifikasi untuk Anda buat sendiri.

Common Changelog, fork yang lebih ketat dari ide ini, memperketat sebagian ini: melarang formulasi entri tertentu, mewajibkan tautan ke perubahan, dan punya pendapat jelas tentang siapa pembacanya. Layak dibaca jika bagian longgar Keep a Changelog adalah yang terus diperdebatkan tim Anda.

Bisakah Keep a Changelog diotomatisasi tanpa membuang git log?

Bisa: turunkan draf dari commit terstruktur, letakkan di Unreleased dengan jenisnya sudah terisi awal, dan wajibkan manusia mengedit formulasinya sebelum rilis dipotong. Peringatan spesifikasi tentang keluarannya, bukan alatnya. Menurunkan draf dari commit tidak masalah. Menerbitkan draf itu tanpa penyuntingan yang ditentangnya.

Mesin menangani pengumpulan dan pemformatan, yang dikuasainya. Manusia menangani seleksi dan formulasi, yang tidak dikuasainya. Conventional commits membahas pembagian dua lapis yang menjadi dasarnya, dan jenis commit mana yang berkaitan dengan kategori mana dari enam kategori di atas. Rangkuman alat changelog kami mencakup apa yang ada untuk separuh pengumpulan.

Di mana Keep a Changelog berhenti menjadi cukup?

Berhenti di distribusi. Keep a Changelog adalah jawaban yang baik untuk “seperti apa berkas ini seharusnya”. Bukan jawaban untuk “bagaimana pengguna kami tahu apa yang berubah”, karena berkas Markdown di repo adalah strategi distribusi yang hanya berhasil jika pengguna Anda adalah kontributor.

Itulah rintangan yang dihadapi kebanyakan tim kedua: berkasnya baik-baik saja, dan tidak ada yang di luar tim membacanya. Menyelesaikannya berarti entri harus menjadi data yang bisa dirender di tempat lain, yang merupakan masalah berbeda dari memformat berkas, dan alasan mengapa contoh changelog mengumpulkan halaman changelog publik alih-alih berkas repositori. Cara mengubah entri itu menjadi sesuatu yang diikuti orang dibahas di cara membangun halaman changelog.

Adopsi spesifikasinya tetap saja. Butuh satu sore, membuat masalah kedua bisa ditangani, dan masih halaman terbaik yang pernah ditulis tentang ini.

FAQ

Apakah Keep a Changelog sebuah standar? Ini konvensi yang diadopsi secara luas, bukan spesifikasi badan standardisasi. Alat (skrip rilis, linter, parser) sering cukup mengasumsikan bentuknya sehingga mengikutinya membeli kompatibilitas.

Apa yang masuk ke bagian Unreleased? Setiap entri untuk perubahan yang sudah di-merge tapi belum dirilis dalam versi bernomor. Ketika rilis dipotong, bagian tersebut diganti nama menjadi versi dan tanggal, dan bagian Unreleased baru yang kosong ditempatkan di atasnya.

Haruskah changelog menggunakan versi semantik? Keep a Changelog merekomendasikannya dan tidak mewajibkannya. Pustaka dan API mendapat manfaat; layanan yang di-deploy terus-menerus biasanya menggantinya dengan tanggal, yang diakomodasi formatnya.

Haruskah perbaikan keamanan ada di changelog sebelum dipublikasikan? Tambahkan entrinya saat perbaikan dirilis, dengan detail cukup untuk operator bisa bertindak dan tidak lebih. Menunda entri hingga tanggal pengungkapan terkoordinasi itu normal; menghilangkannya tidak.

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, Perbandingan alat changelog