Tag git, rilis, dan changelog Anda

Tag git, rilis, dan entri changelog adalah tiga catatan berbeda dari peristiwa yang sama, dan mencampuradukkannya membuat changelog diam-diam melenceng dari apa yang sebenarnya dirilis. Tag menandai commit. Rilis mengemas tag itu dengan artefak dan deskripsi. Entri changelog menjelaskan, dengan istilah yang bisa dipakai pembaca di luar repositori, apa yang berubah. Biasanya terjadi berdekatan waktunya, dan justru karena itu mudah memperlakukannya sebagai satu langkah alih-alih tiga, dan justru karena itu jaraknya baru terlihat berbulan-bulan kemudian, saat seseorang bertanya “apa yang dirilis di v2.4” dan jawaban jujurnya butuh penggalian sungguhan.

Apa sebenarnya perbedaan di antara ketiganya?

Tag adalah yang paling mekanis dari ketiganya: git tag v2.4.0 dan selesai, tanpa syarat apa pun yang harus menjelaskan isinya. Rilis menambahkan deskripsi dan biasanya artefak yang bisa diunduh, dan audiensnya tetap developer yang tahu apa itu halaman rilis. Entri changelog adalah satu-satunya dari ketiganya yang ditulis untuk pembaca yang mungkin tidak pernah membuka repositori, itu sebabnya ini yang butuh perhatian editorial paling banyak dan paling mungkin dilewati di bawah tekanan tenggat.

Apakah setiap tag git butuh entri changelog?

Tidak, dan memperlakukannya satu-lawan-satu adalah kesalahan umum. Tag bisa menandai tonggak internal, release candidate, atau hotfix yang tidak pernah menjangkau kebanyakan pengguna; tak satu pun dari itu harus punya entri publik. Ujinya sama dengan yang menentukan apakah sesuatu layak masuk changelog sama sekali: apakah pengguna atau pemanggil akan menyadari atau mempedulikannya. Kebanyakan tag lolos uji itu. Beberapa, seperti tag yang dibuat hanya untuk memicu pipeline CI, tidak pernah.

Apakah setiap entri changelog butuh tag sendiri?

Tidak selalu, dan di sinilah tim yang deploy berkelanjutan berbeda dari tim yang merilis paket berversi. Produk SaaS yang deploy beberapa kali sehari bisa mengelompokkan beberapa deploy di bawah satu entri changelog bertanggal tanpa tag 1:1 per deploy; pustaka yang dipublikasikan di registri paket biasanya butuh satu tag per versi yang dipublikasikan. Go modules dan Swift Package Manager me-resolve versi dari tag itu sendiri; di npm atau PyPI registri menyimpan versi yang dipublikasikan, dan tag adalah cara siapa pun memetakan versi itu kembali ke sumbernya. Repositori dengan beberapa paket yang diversi secara independen harus memutuskan ini per paket, bukan sekali untuk seluruh repo; changelog monorepo membahas bagaimana prefiks tag dan cakupan changelog seharusnya mengikuti batas paket, bukan batas folder. Semantic versioning dan changelog Anda membahas bagaimana nomor versi itu sendiri seharusnya memetakan ke kategori changelog; tag adalah mekanisme yang membuat nomor versi bisa diverifikasi terhadap kode sebenarnya.

Bagaimana deskripsi rilis seharusnya berkaitan dengan entri changelog?

Keduanya bisa jadi teks yang sama, tapi hanya jika audiens keduanya benar-benar sama, yang lebih jarang dari kelihatannya. Halaman rilis di host kode dibaca hampir seluruhnya oleh developer; jika produk juga punya pengguna non-teknis yang membaca changelog, menduplikasi deskripsi rilis apa adanya mengirim istilah internal dan formulasi berorientasi kode ke pembaca yang butuh versi bahasa awam. Pola paling bersih: tulis entri changelog sebagai artefak utama yang berorientasi pembaca, dan biarkan deskripsi rilis menautkannya atau menyimpan ringkasan yang lebih pendek dan teknis untuk audiens yang sudah nyaman di sana.

# Rilis v2.4.0 (GitHub, untuk developer)
Meningkatkan pipeline laporan ke mesin agregasi baru. Lihat changelog
untuk ringkasan berorientasi pelanggan:
https://example.com/changelog#v2.4.0

## 2026-09-07 (Changelog, berorientasi pelanggan)
### Added
- Laporan sekarang dimuat dalam kurang dari satu detik, bahkan untuk
  akun dengan lebih dari satu juta baris.

Rilis yang sama, dua dokumen, masing-masing dengan formulasinya sendiri untuk pembacanya sendiri.

Dari mana sebenarnya entri changelog berasal?

Dari dua titik awal, dan kebanyakan pipeline nyata adalah campuran keduanya. Bisa dihasilkan dari pesan commit pada saat tag, yang cepat dan tidak pernah melewatkan pull request yang digabung; dari conventional commits ke changelog membahas pipeline itu secara lengkap. Atau bisa ditulis manual, terpisah dari tag sepenuhnya, disinkronkan dengan saat fitur dianggap selesai alih-alih saat kode digabung. Entri yang dihasilkan konsisten tapi mewarisi setiap pesan commit yang samar; entri yang ditulis manual lebih jelas tapi butuh seseorang untuk benar-benar menulisnya. Kebanyakan tim yang mengotomatisasi tetap menjaga langkah penyuntingan ringan pada teks yang dihasilkan sebelum menjadi entri publik, disiplin yang sama yang direkomendasikan Keep a Changelog, dalam praktik, terlepas dari dari mana teks mentahnya awalnya berasal.

Apa yang rusak ketika ketiganya tidak sinkron?

Kepercayaan pada yang dicek pembaca lebih dulu. Tag yang ada tanpa entri changelog yang sesuai terlihat, dari sisi pembaca changelog, seolah tidak terjadi apa-apa minggu itu. Entri changelog tanpa tag atau rilis yang sesuai membuat mustahil bagi seseorang yang men-debug masalah produksi untuk checkout kode persis yang live saat entri dipublikasikan. Solusinya bukan otomatisasi sempurna, tapi satu sumber kebenaran untuk pemetaan itu: satu tempat, meski hanya checklist proses rilis itu sendiri, yang menyatakan perubahan yang bisa dirilis mendapat ketiganya, dalam commit atau pull request yang sama yang memperkenalkannya.

FAQ

Haruskah entri changelog dihasilkan otomatis dari tag git? Bisa jadi titik awal, tapi tag saja tidak membawa deskripsi berorientasi pembaca, hanya rentang commit. Generasi otomatis harus membaca pesan commit dalam rentang itu, bukan hanya keberadaan tag, untuk menghasilkan sesuatu yang bisa dipakai.

Bagaimana jika kami tidak men-tag setiap rilis? Maka entri changelog menjadi catatan utama, dan tetap harus membawa tanggal dan, jika produk punya, nomor versi, sehingga entri tetap jadi sesuatu yang bisa dirujuk pembaca nanti bahkan tanpa tag yang sesuai.

Haruskah tag pra-rilis (seperti v2.4.0-rc.1) punya entri changelog? Umumnya tidak. Release candidate untuk pengujian internal atau beta, dan entri changelog untuknya melatih pembaca mengharapkan entri untuk versi yang mungkin tidak pernah dirilis persis seperti dideskripsikan. Simpan entri untuk tag yang mencapai ketersediaan umum.

Bisakah satu entri changelog mencakup beberapa tag git? Ya, dan sering kali seharusnya begitu untuk tim yang sering men-tag. Kelompokkan tag terkait di bawah satu entri bertanggal yang mendeskripsikan perubahan bersih, alih-alih mempublikasikan entri tipis per tag yang memecah satu fitur ke beberapa bacaan.

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, Dokumentasi developer