Apa itu changelog? Pengertian dan contoh entri
5 menit baca diperbarui
Changelog adalah catatan bertanggal tentang apa yang berubah dalam sebuah produk, ditulis untuk orang-orang yang terdampak oleh perubahan itu, bukan untuk tim yang merilisnya. Setiap entri menyebutkan satu perubahan, menyatakan kapan itu berlaku, dan menyatakan apa yang harus dilakukan pembaca, yang pada kebanyakan entri adalah tidak ada apa-apa. Bagian terakhir itulah yang membedakan changelog dari log commit: log commit adalah catatan untuk orang yang menulis kode, changelog adalah catatan untuk orang yang memakainya.
Apa itu changelog, sebenarnya?
Daftar entri bertanggal, terbaru di atas, masing-masing menjelaskan satu perubahan dalam istilah yang bisa diperiksa pembaca. Bukan apa yang dibangun tim, tapi apa yang sekarang berbeda. “Merefaktor layanan billing” adalah pesan commit. “Faktur sekarang menampilkan pajak sebagai baris terpisah” adalah entri changelog, karena memberi tahu pembaca sesuatu yang bisa mereka periksa di akun mereka sendiri.
Formatnya sudah lama ada dan sengaja dibuat sederhana: judul per rilis atau per hari, daftar singkat di bawahnya, kadang label kategori. Keep a Changelog adalah spesifikasi yang paling banyak dikutip untuk bentuk ini (cara kerjanya di repositori sungguhan), dan ada karena kebanyakan proyek yang melewatkan spesifikasi berakhir dengan membuang riwayat commit sebagai gantinya, yang menjawab pertanyaan berbeda dari yang dibawa pembaca.
| Dokumen | Ditulis untuk | Menjawab |
|---|---|---|
| Changelog | Siapa pun yang memakai produk | Apa yang berubah, dan kapan? |
| Log commit | Tim yang menulis kode | Apa yang dikerjakan, dalam urutan apa? |
| Catatan rilis | Pengguna yang memutuskan untuk update | Apa yang bisa saya lakukan sekarang? |
| Catatan patch | Pemain atau pengguna dari satu perbaikan tertentu | Apa yang diperbaiki rilis ini? |
| Roadmap | Siapa pun yang bertanya-tanya apa selanjutnya | Apa yang direncanakan, dan sejauh mana? |
Kelimanya tumpang tindih dalam praktiknya, tapi bukan dokumen yang sama, dan bedanya ada pada siapa yang memegangnya saat membaca. Changelog adalah yang dibangun untuk dicari dan ditautkan kembali nanti, sehingga entrinya lebih butuh tanggal dan URL stabil dibanding yang lain. Roadmap adalah satu-satunya dari kelima dokumen itu yang melihat ke depan; contoh roadmap produk menunjukkan enam format yang bisa diambilnya.
Apa sebenarnya isi entri changelog?
Empat hal, dalam urutan ini: apa yang berubah, dinyatakan dalam istilah yang akan disadari pengguna atau pemanggil; kapan itu berlaku; termasuk kategori apa (added, fixed, changed, removed adalah empat yang umum); dan, ketika penting, apa yang harus dilakukan pembaca. Tautan ke detail lebih lanjut dipersilakan. Paragraf justifikasi internal tidak, karena pembaca tidak bertanya mengapa, mereka bertanya apa.
## 2026-09-07
### Added
- Faktur sekarang menampilkan pajak sebagai baris terpisah, dalam mata
uang akun pelanggan.
### Fixed
- Mengekspor laporan sebagai CSV tidak lagi menghilangkan baris terakhir
saat laporan melebihi 10.000 baris.
Bentuk itu berskala dari update dua baris hingga seratus entri dalam satu rilis tanpa mengubah struktur, dan itulah uji sebenarnya apakah sebuah format berfungsi: apakah terbaca sama pada minggu yang sibuk maupun yang tenang.
Adakah template changelog yang bisa disalin?
Ada. Ini bentuk yang sama dengan empat kategori umum, siap ditempel ke CHANGELOG.md atau sebuah
halaman. Hapus judul mana pun yang tidak punya isi pada rilis tertentu.
# Changelog
## 2026-10-18
### Added
- [Apa yang kini bisa dilakukan pengguna dan sebelumnya tidak bisa.]
### Changed
- [Apa yang kini bekerja berbeda, dan yang harus dilakukan pembaca.]
### Fixed
- [Gejala yang dilihat pengguna, yang kini sudah hilang.]
### Removed
- [Apa yang sudah tiada, dan apa yang dipakai sebagai gantinya.]
Untuk dokumen yang lebih panjang per rilis, template release notes
menambahkan baris ringkasan dan bagian breaking change. Untuk lima entri jadi dengan catatan
mengapa masing-masing berhasil, lihat contoh changelog.
Jika changelog disimpan di repositori, CHANGELOG.md membahas cara menjaga
file itu tetap mutakhir, dari bagian Unreleased di paling atas sampai apa yang sebaiknya tidak
dimasukkan.
Siapa yang menulis changelog, dan kapan?
Siapa pun yang membuat perubahan, pada saat dirilis, bukan penulis teknis yang merekonstruksinya dari tiket seminggu kemudian. Yang menyentuh kode tahu apa yang benar-benar berubah bagi pengguna; ringkasan yang ditulis belakangan cenderung menjelaskan tiketnya alih-alih apa yang sebenarnya dirilis, dan itu biasanya lebih luas atau lebih sempit dari cakupan sebenarnya. Beberapa tim menambahkan langkah review sebelum entri menjadi publik, terutama untuk menangkap bahasa internal yang menyelip, dan review itu harus cukup cepat agar entri tetap rilis di hari yang sama.
Di mana seharusnya changelog berada?
Di halaman sendiri, di URL yang stabil, disebarkan sebagai feed. Terkubur di menu pengaturan atau tag rilis di host kode, hanya menjangkau orang yang sudah tahu ke mana harus mencari. Halaman publik bisa ditautkan dari tiket dukungan, dikutip dalam ulasan, atau dilanggan. Feed sama pentingnya dengan halamannya: pembaca yang mengecek changelog produk sebulan sekali itu jarang, yang berlangganan tidak, dan hanya feed yang melayani kelompok kedua. Cara membangun halaman changelog publik membahas halamannya sendiri, dari URL sampai opsi berlangganan.
Apa bedanya dengan catatan rilis?
Keduanya terus-menerus tertukar, dan cukup berbeda sehingga mencampur keduanya menghasilkan dokumen yang tidak melayani kedua pembaca dengan baik. Changelog vs catatan rilis membahas perbedaannya secara lengkap; singkatnya, changelog adalah catatan lengkap dan kronologis, sementara catatan rilis adalah subset terkurasi, ditulis agar sebuah update terdengar layak untuk dimiliki. Sebuah produk biasanya butuh keduanya, ditujukan untuk momen berbeda dalam hari pembaca.
Apa yang membuat changelog layak dibaca?
Kekhususan dan kejujuran tentang cakupannya sendiri. “Berbagai perbaikan bug” adalah kalimat yang mengajarkan pembaca untuk berhenti membuka halaman itu, karena tidak menjanjikan apa pun yang bisa mereka periksa. Entri yang menyebutkan perilaku persis yang berubah, bahkan untuk perbaikan kecil, adalah yang membuat langganan tetap hidup. Disiplin ini juga berlaku pada apa yang dihilangkan: changelog yang hanya mengumumkan keberhasilan dan tidak pernah perbaikan untuk sesuatu yang rusak terbaca seperti pemasaran yang menyamar sebagai changelog, dan pembaca menyadarinya.
Disiplin versioning juga penting. Semantic versioning dan changelog Anda membahas bagaimana nomor versi dan entri seharusnya cocok, sehingga pembaca yang menelusuri riwayat versi mendapat sinyal yang sama dua kali, bukan dua sinyal berbeda.
Bagaimana changelog dihasilkan?
Dengan dua cara, dan kebanyakan pengaturan nyata adalah campuran. Generasi otomatis membaca pesan commit, biasanya dalam format Conventional Commits, dan mengubahnya menjadi entri tanpa ada yang menyentuh hasilnya; dari conventional commits ke changelog membahas pipeline itu. Generasi terkurasi berarti seseorang menulis atau menyunting setiap entri secara manual. Hasil otomatis lebih cepat dan tidak pernah melewatkan pull request yang digabung, tapi mewarisi setiap pesan commit yang samar apa adanya, sehingga kebanyakan tim yang mengotomatisasi tetap menyimpan langkah penyuntingan ringan sebelum publikasi alih-alih menampilkan hasil mentah.
Di GitHub, draf pertama bisa datang dari platform itu sendiri, yang dapat membuat release notes dari
pull request yang digabung sejak tag sebelumnya. Release notes
GitHub membahas file release.yml yang mengelompokkannya dan
putaran penyuntingan yang membuatnya enak dibaca.
FAQ
Apakah setiap produk butuh changelog? Produk mana pun dengan pengguna yang terdampak oleh perubahan membutuhkannya, entah itu aplikasi SaaS, alat internal, atau API publik. Bentuknya menyesuaikan (changelog API terbaca berbeda dari aplikasi konsumen), kebutuhannya tidak.
Apa itu changelog dalam istilah software? Definisi yang sama seperti di atas: daftar bertanggal dan kronologis tentang apa yang berubah dalam software, ditulis untuk yang memakainya, bukan yang membangunnya.
Bisakah changelog dihasilkan otomatis dari commit? Ya, dan banyak tim melakukan persis itu, biasanya dari pesan berformat Conventional Commits. Kompromisnya, entri yang dihasilkan sejelas pesan commit asalnya, sehingga langkah review sebelum publikasi menangkap yang perlu diformulasikan ulang.
Apakah changelog sama dengan riwayat versi? Cukup mirip sehingga istilahnya dipakai bergantian. Riwayat versi kadang hanya daftar nomor versi dan tanggal tanpa deskripsi; changelog selalu menyertakan apa yang berubah.
Klaim teknis dalam artikel ini belum ditinjau secara independen. Jika ada yang keliru, beri tahu kami dan kami akan memperbaikinya.