Log Perubahan Modul, Bukan Tempahan Git Log
Enam commit sehari diringkas satu baris changelog modul: cara memilah perubahan yang layak dicatat manusia.
Ringkasan
Enam commit teknis itu ternyata cukup dicatat jadi satu baris changelog aja, karena yang penting bukan jumlah commit tapi perubahan perilaku yang dirasain user. Jadi jangan asal copas git log mentah, mending dikurasi manual biar dampak fungsionalnya jelas. Terus karena API-nya tetap kompatibel dan cuma aturan bisnis yang berubah, kategori paling pas ya "Changed", bukan "Fixed".
Saya membuka berkas scripts/unit_testing/qa-reports/modules/layanan.md di proyek fiktif KotaPortal. Di layar, tabel "Riwayat perubahan" hanya menampilkan satu baris untuk pembaruan terbaru. Kolomnya terstruktur dengan jelas: Tanggal, Perubahan, Pemicu, dan Perlu QA re-run. Baris tunggal ini merangkum perubahan perilaku yang luas secara utuh. Transisi status dibebaskan, catatan penolakan bersyarat ditambahkan, wizard kini menawarkan semua status, dan rute mockup dihapus dari sistem.
Pada hari yang sama, repositori mencatat enam commit terpisah, termasuk pembaruan fitur wizard dan penghapusan berkas mockup admin. Awalnya, saya mengira pergerakan kartu di papan proyek dari status "in-progress" ke "done" hanyalah aktivitas chore yang berisik dan tidak layak dicatat dalam dokumentasi resmi. Saya berasumsi bahwa setiap commit harus dicatat secara individual agar transparan, dan mengabaikan pergerakan tiket sebagai noise administratif belaka.
Asumsi itu keliru. Baris changelog tersebut ada justru karena aktivitas chore tersebut mengonsolidasikan perubahan kontrak perilaku ke satu titik yang bermakna. Enam commit teknis tersebut bermuara pada satu perubahan fungsional yang perlu dipahami oleh manusia, bukan mesin. File changelog modul menampung baris berdasarkan tanggal, pemicu, dan penanda pelaksanaan ulang pengujian jaminan kualitas, bukan sekadar salinan mentah dari riwayat versi. Pendekatan log perubahan modul bukan git log yang mentah membuat tim bisa fokus pada nilai yang sampai ke pengguna.
Taksonomi Perubahan dan Kompatibilitas API
Standar industri seperti Keep a Changelog menyediakan taksonomi enam tipe perubahan[1][5] untuk membantu memilah kata yang tepat dalam dokumentasi. Perbedaan antara kategori Changed dan Fixed sangat menentukan akurasi pencatatan. Sebuah pembaruan dikategorikan sebagai "Changed" ketika perilaku sebelumnya bekerja sesuai maksud, namun kini bekerja dengan cara yang berbeda[5].
Dalam kasus pembaruan modul layanan ini, antarmuka pemrograman aplikasi tetap kompatibel. Tidak ada perubahan pada endpoint atau struktur muatan data. Hanya aturan bisnis internal yang diperbarui. Hal ini sejalan dengan prinsip Semantic Versioning, di mana pembaruan minor atau patch punya arti spesifik soal kompatibilitas API tanpa merusak integrasi yang sudah ada [2]. Pemisahan arti ini memastikan bahwa konsumen API tidak perlu mengubah kode mereka, meskipun logika di balik layar telah mengalami penyempurnaan.
Kurasi Manual Melampaui Generator Otomatis
Generator catatan rilis otomatis dari platform hosting git memang berguna sebagai titik awal penyusunan. Namun, alat tersebut pada dasarnya hanya menyusun daftar pull request yang telah digabungkan. Dokumentasi resmi platform tersebut secara eksplisit menyatakan bahwa pengembang wajib memeriksa catatan yang dihasilkan[4] untuk memastikan akurasinya sebelum dipublikasikan.
Daftar mentah ini tetap memerlukan kurasi manual untuk memastikan bahwa catatan tersebut menjelaskan dampak perilaku secara akurat bagi pengguna akhir, bukan sekadar mencantumkan judul commit teknis yang ambigu. Mengandalkan generator otomatis tanpa penyuntingan manusia sering kali menghasilkan dokumentasi yang membingungkan, karena judul commit sering kali ditulis untuk konteks pengembang, bukan untuk konteks pengguna atau penguji kualitas.
Memisahkan dokumentasi perilaku dari tumpukan riwayat commit teknis memungkinkan tim untuk menjawab pertanyaan mendasar tentang apa yang berubah dalam sistem. Dokumentasi yang baik berfokus pada dampak fungsional, memberikan kejelasan yang tidak dapat diberikan oleh daftar hash commit yang panjang.