Format berkas changelog: JSON, YAML, atau cukup Markdown

Sebagian besar tim memulai changelog sebagai berkas Markdown karena itu jalur dengan resistansi paling kecil: bisa dibaca dalam diff pull request, bisa dibaca di GitHub tanpa merender apa pun, dan familiar bagi siapa pun yang pernah menulis README. Pilihan itu berjalan baik sampai sesuatu selain manusia perlu membaca berkas itu, halaman, widget, ringkasan email, dan saat itu format berhenti gratis. Otomasi changelog membahas kebutuhan struktural secara umum, tipe, tanggal, badan, dan tautan; ini membahas format berkas mana yang benar-benar memberikan struktur itu dan berapa biaya untuk mencapainya di masing-masing format.

Apa yang salah dengan changelog Markdown biasa?

Tidak ada, sampai sesuatu perlu mem-parsingnya kembali ke dalam field. Judul, tanggal, dan daftar berpoin di bawahnya remeh dibaca bagi manusia dan sungguh sulit di-parsing dengan andal, karena Markdown tidak punya skema: tanggal bisa ada di judul, tebal di baris pertama, atau sama sekali tidak ada di entri lama, dan setiap variasi itu adalah Markdown valid yang dibaca benar oleh manusia dan tidak oleh parser. Tim yang mengotomasi changelog Markdown biasanya berakhir menulis parser regex khusus yang rusak begitu format sebuah entri sedikit saja melenceng, yang sering terjadi, karena tidak ada yang memaksa konsistensi saat menulis.

Apa yang sebenarnya didapat dari format terstruktur?

Jaminan bahwa setiap entri punya bentuk yang sama, diperiksa saat entri ditulis alih-alih ditebak saat dibaca. Berkas JSON atau YAML dengan skema yang ditentukan, tipe, tanggal, versi, audiens, badan, tautan, gagal dengan berisik jika field wajib hilang, sama seperti respons API yang ketat; berkas Markdown hanya merender apa pun yang ada, benar atau tidak. Perbedaan itu tak terlihat sampai hari sebuah skrip butuh tanggal setiap entri untuk mengurutkan feed, dan separuh entri menyimpannya di tempat berbeda.

# CHANGELOG.yml
- date: 2026-09-05
  type: breaking
  version: v2
  audience: api
  body: "POST /invoices now rejects a currency mismatch instead of silently converting."
  link: /blog/api-changelog/

Apakah itu berarti berkas yang bisa dibaca manusia harus hilang?

Tidak, dan mencoba membuat berkas YAML atau JSON berperan ganda sebagai apa yang dibaca manusia dalam pull request biasanya kesalahan ke arah sebaliknya: meninjau diff JSON bersarang lebih buruk daripada meninjau kalimat prosa, dan peninjau yang harus mem-parsing struktur data secara mental untuk menangkap kesalahan kata-kata adalah peninjau yang akhirnya berhenti menangkap kesalahan kata-kata. Kedua format bisa berdampingan: data terstruktur adalah sumber kebenaran yang dibaca pipeline otomasi, dan rendering Markdown atau HTML yang dihasilkan adalah yang benar-benar ditinjau dan dibaca manusia, diproduksi dari berkas terstruktur alih-alih dirawat manual di sampingnya.

Format terstruktur mana yang sebenarnya lebih mudah diedit manual, JSON atau YAML?

YAML, bagi siapa pun yang menulis entri secara manual alih-alih lewat generator, karena ia menghilangkan penguncian kutip dan pencocokan kurung yang dituntut JSON untuk setiap string dan objek bersarang. Trade-off-nya adalah sensitivitas spasi YAML gagal secara diam dengan cara yang biasanya tidak dilakukan ketidakcocokan kurung JSON: parser JSON langsung menolak input yang cacat, sementara parser YAML bisa menerima berkas yang salah indentasi dan begitu saja mem-parsingnya ke struktur yang salah, yang merupakan kegagalan lebih buruk karena tidak ada yang memberi tahu Anda itu terjadi. Jika entri selalu hanya ditulis oleh skrip, trade-off ini sebagian besar hilang dan parsing JSON yang lebih ketat menjadi pilihan default yang lebih aman.

Apakah halaman changelog butuh format terstruktur sendiri, terpisah dari berkas yang memasoknya?

Bukan yang terpisah, yang sama dirender berbeda. Halaman changelog membahas cara membuat halaman itu sendiri bisa dibaca mesin lewat feed JSON dan markup schema.org; feed itu adalah output yang dihasilkan, bukan sumber kebenaran kedua yang harus disinkronkan dengan berkas yang mendasarinya. Merawat data terstruktur secara manual di dua tempat, berkas sumber dan feed halaman, adalah cara keduanya akhirnya melenceng, jadi keputusan format berkas yang diambil di sini seharusnya menjadi satu-satunya hal yang darinya semua yang hilir, halaman, widget, email, dihasilkan, tidak pernah disalin manual.

Apakah biaya migrasi mengubah changelog Markdown yang ada ke format terstruktur sepadan?

Biasanya hanya begitu otomasi menjadi tujuan sebenarnya, bukan sebelumnya. Proyek satu orang yang menerbitkan berkas Markdown di README GitHub tidak punya kebutuhan otomasi nyata, dan mengubahnya ke YAML tidak membeli apa pun selain seremoni. Konversi itu membayar dirinya sendiri saat lebih dari satu konsumen hilir, halaman, email ringkasan, feed publik, butuh membaca data yang sama, karena itu persis titik di mana ketidakkonsistenan parser Markdown mulai menghasilkan output yang terlihat salah alih-alih hanya menjengkelkan untuk dirawat.

FAQ

Bisakah changelog Markdown dibuat bisa di-parsing tanpa mengubah format sepenuhnya? Sebagian, dengan frontmatter: blok YAML kecil di atas setiap entri (tanggal, tipe, versi) di samping badan Markdown untuk prosa. Ini mendapatkan field terstruktur yang dibutuhkan parser tanpa memaksa seluruh entri ke JSON atau YAML, dan ini titik tengah yang masuk akal bagi tim yang belum siap untuk migrasi penuh.

Apakah format berkas penting untuk SEO atau untuk bagaimana halaman changelog peringkat? Tidak secara langsung. Mesin pencari membaca halaman yang dirender, bukan berkas sumber, jadi format berkas tidak terlihat bagi mereka; yang penting bagi halaman itu sendiri adalah apakah ia bisa dibaca mesin dengan haknya sendiri, yang merupakan urusan terpisah dari apa yang menghasilkannya.

Haruskah setiap entri changelog melalui berkas yang sama, atau bisakah tipe dipisah ke beberapa berkas? Satu berkas lebih sederhana sampai volume entri membuatnya sulit di-diff atau ditinjau; memisah berdasarkan tahun atau kategori adalah katup pelepas yang masuk akal begitu diff satu berkas menjadi terlalu besar untuk ditinjau dengan wajar, tapi itu menambah langkah penggabungan sebelum apa pun di hilir bisa membaca “semua entri” sebagai satu daftar.

Apakah ada format berkas changelog standar, seperti ada standar untuk RSS? Tidak ada yang diadopsi secara luas. Keep a Changelog mengusulkan konvensi Markdown, dan beberapa alat punya format sendiri; sebuah changeset adalah berkas Markdown dengan frontmatter YAML yang menyebut paket dan kenaikan versinya, yaitu pola frontmatter yang dijelaskan di atas. Tidak satu pun dari ini adalah format yang dibaca alat lain langsung dari awal seperti pembaca RSS memahami RSS secara universal.

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

Terkait di changeloop: Perbandingan alat changelog, Generator changelog