CHANGELOG.md: apa isinya dan cara menjaganya tetap mutakhir

CHANGELOG.md adalah berkas Markdown di root repositori yang mendaftar, untuk setiap versi yang dirilis, apa yang berubah dalam bahasa yang bisa ditindaklanjuti pengguna proyek. Berkas ini dibaca oleh orang yang memutuskan apakah akan upgrade, oleh orang yang men-debug setelah upgrade, dan oleh package registry serta alat rilis yang menampilkannya di halaman proyek. Format yang diikuti kebanyakan proyek adalah yang dijelaskan di keepachangelog.com: versi terbaru di atas, bagian Unreleased di atasnya, dan entri dikelompokkan di bawah Added, Changed, Deprecated, Removed, Fixed, dan Security.

Apa itu berkas CHANGELOG.md?

Ini adalah riwayat proyek yang bisa dibaca manusia, satu versi demi satu versi, disimpan di sebelah kode agar ikut terkirim bersamanya. Bedanya dengan git log ada pada audiens dan seleksi: git log mencatat setiap commit untuk orang yang menulisnya, sedangkan changelog mencatat perubahan yang akan disadari pengguna, ditulis untuk orang yang tidak menulisnya. Commit yang mengganti nama variabel internal tidak punya baris changelog. Commit yang mengubah timeout default punya satu baris, meski diff-nya hanya satu karakter.

Berkas ini berada di root repositori dengan nama persis itu karena alat-alat mencarinya di sana. GitHub menautkannya dari halaman repositori, npm dan PyPI menampilkannya jika disertakan dalam paket, dan alat rilis seperti release-please dan semantic-release membaca dan menulisnya di tempat. Huruf kecil changelog.md dan CHANGES.md juga berfungsi untuk manusia, tapi sebagian alat hanya mencari nama kanonisnya.

Seperti apa CHANGELOG.md yang lengkap?

Contoh singkat yang benar lebih berharga daripada penjelasan panjang. Contoh ini mengikuti tata letak Keep a Changelog 1.1.0 dan semantic versioning untuk nomornya.

# Changelog

Semua perubahan penting pada proyek ini dicatat di sini.
Format: Keep a Changelog. Versi: Semantic Versioning.

## [Unreleased]

### Added
- Flag `--dry-run` pada `deploy` mencetak rencana tanpa menerapkannya.

## [2.3.1] - 2026-10-01

### Fixed
- Pencarian tidak lagi gagal pada kueri yang mengandung tanda hubung.
  Rusak sejak 2.3.0.

### Security
- Memperbaiki path traversal di handler berkas statis. Upgrade hari
  ini jika Anda melayani berkas unggahan pengguna.

## [2.3.0] - 2026-09-18

### Added
- Ekspor streaming. Berkas di atas 100 MB tidak lagi time out.

### Deprecated
- `legacyAuth()` masih berfungsi tapi akan dihapus di 3.0.
  Gunakan `auth()`.

[Unreleased]: https://github.com/acme/tool/compare/v2.3.1...HEAD
[2.3.1]: https://github.com/acme/tool/compare/v2.3.0...v2.3.1
[2.3.0]: https://github.com/acme/tool/compare/v2.2.0...v2.3.0

Empat detail membawa sebagian besar nilainya. Setiap versi punya tanggal dalam format ISO, jadi pembaca bisa mencocokkannya dengan kapan masalah mereka mulai. Setiap judul versi adalah tautan ke tampilan compare, jadi diff lengkapnya tinggal satu klik. Sebuah perbaikan menyebut versi mana yang merusaknya. Dan bagian Security berdiri terpisah, jadi orang yang memindai “apakah saya perlu upgrade sekarang” menemukannya dalam hitungan detik.

Bagaimana menjaga CHANGELOG.md tetap mutakhir?

Tulis barisnya di pull request yang sama dengan perubahannya, di bawah Unreleased, dan pindahkan bagian itu ke judul versi saat Anda merilis. Itu seluruh metodenya. Berkas menjadi basi ketika barisnya ditulis belakangan oleh orang lain, saat rilis, dari daftar pesan commit yang bukan tulisannya.

Dua hal membuat kebiasaan ini melekat. Pertama, pemeriksaan di CI yang menggagalkan pull request yang menyentuh src/ tanpa menyentuh changelog, dengan label untuk melewatinya pada perubahan yang tidak berdampak ke pengguna; pemeriksaan changelog sebagai GitHub Action menunjukkan versi empat puluh barisnya. Kedua, langkah rilis yang mengganti nama Unreleased menjadi versi dan tanggal dalam satu perintah, jadi tidak ada yang harus mengingatnya secara manual. Siapa yang menulis changelog membahas cara tim menyelesaikan pertanyaan tugas siapa baris itu.

Haruskah changelog dihasilkan dari commit?

Generator memberi Anda draf yang lengkap; ia tidak memberi Anda changelog. Alat yang dibangun di atas conventional commits, dan otomasi rilis seperti release-please, membaca awalan feat:, fix:, dan BREAKING CHANGE: lalu menghasilkan daftar terkelompok dengan setiap pull request tertaut. Daftarnya hanya sebaik subjek commit-nya, dan subjek commit menggambarkan kode.

Jalan tengah yang berhasil adalah menghasilkan, lalu mengedit. Biarkan alat membuat bagian Unreleased dari commit, dan biarkan pull request rilis menulis ulang baris-baris yang akan dibaca pengguna: gejala alih-alih nama fungsi, pengaturan yang berpindah alih-alih berkas yang berubah. Dari conventional commits ke changelog membahas pipeline-nya, dan generator changelog di sisi browser sudah cukup untuk mendapatkan draf dari git log yang ditempel tanpa memasang apa pun.

Apa yang tidak boleh masuk ke CHANGELOG.md?

Refactor internal, kenaikan dependensi tanpa perubahan perilaku, commit khusus pengujian, konfigurasi CI, dan perubahan format. Semua itu tempatnya di riwayat git, di mana siapa pun yang membutuhkannya bisa menemukannya. Memasukkannya mengubur baris yang penting dan melatih pembaca untuk melewati berkas itu.

Hal lain yang harus dibuang adalah versi pemasaran dari sebuah perubahan. “Ekspor super kencang” tidak memberi pembaca apa pun yang bisa diperiksa. “Ekspor kini streaming; berkas di atas 100 MB tidak lagi time out” memberinya. Berkas ini adalah dokumen referensi, dan nadanya harus sesuai: baris pendek, kata benda konkret, versi atau tanggal pada semuanya. Keep a Changelog, diterapkan membahas bagian spesifikasi yang paling sering ditinggalkan tim, dan format berkas changelog membahas kapan sumber JSON atau YAML di sebelah berkas Markdown layak dipertahankan.

Apakah produk dengan halaman changelog masih butuh berkasnya?

Library butuh, karena berkas itulah yang ditampilkan package registry dan yang dibaca developer secara offline. Produk SaaS tanpa artefak yang bisa dipasang bisa cukup dengan halamannya saja, karena penggunanya tidak pernah melihat repositori. Banyak tim menjalankan keduanya: berkas sebagai catatan engineering, dan halaman changelog publik yang ditulis darinya untuk audiens yang lebih luas, dengan pembagian detail seperti yang dijelaskan changelog vs release notes. Jika halaman diisi dari berkas, jadikan berkas sumber kebenaran dan hasilkan halamannya, sehingga hanya ada satu tempat untuk mengedit.

FAQ

Apa perbedaan CHANGELOG.md dan release notes? Changelog adalah catatan berjalan yang lengkap dari setiap perubahan penting, disimpan di repositori. Release notes adalah pesan tentang satu rilis, sering lebih pendek dan ditulis ulang untuk audiens yang lebih luas. Banyak proyek menerbitkan bagian changelog sebuah versi sebagai release notes-nya.

Di mana CHANGELOG.md seharusnya berada? Di root repositori, dengan nama persis itu, agar GitHub, package registry, dan alat rilis menemukannya. Monorepo menyimpan satu per paket, di sebelah manifest masing-masing paket.

Haruskah saya menghasilkan CHANGELOG.md dari commit git? Hasilkan drafnya, lalu edit baris yang akan dibaca pengguna. Pesan commit menggambarkan perubahan kode; changelog menggambarkan apa yang disadari pengguna. Alat seperti conventional-changelog dan release-please menghasilkan titik awal yang baik.

Apakah setiap commit butuh entri changelog? Tidak. Hanya perubahan yang bisa disadari pengguna proyek: kemampuan baru, perubahan perilaku, deprecation, penghapusan, perbaikan, dan patch keamanan. Refactor, perubahan pengujian, dan edit CI tetap di riwayat git.

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

Terkait di changeloop: Generator changelog, Contoh changelog