Templat catatan rilis

Templatnya

Segala sesuatu dalam tanda kurung siku adalah placeholder. Segala sesuatu yang lain layak dipertahankan, termasuk urutannya: pengguna mencari hal yang memengaruhi mereka, jadi perubahan yang merusak kompatibilitas datang lebih dulu dan pekerjaan internal tidak muncul sama sekali.

## [Produk] [versi] - [tanggal]

[Satu kalimat yang menjelaskan tujuan rilis ini. Lewati untuk rilis rutin.]

### Perubahan yang merusak kompatibilitas
- [Apa yang rusak, apa yang harus diubah, dan sampai kapan. Tautkan
  langkah migrasinya.]

### Baru
- [Kemampuan, dijelaskan sebagai hasil. "Kunci sebuah filter dan
  gunakan lagi", bukan "model SavedView ditambahkan".]

### Ditingkatkan
- [Apa yang lebih cepat, lebih jelas, atau lebih andal, dan kira-kira
  seberapa banyak.]

### Diperbaiki
- [Gejala yang dilihat pengguna, bukan penyebab di dalam kode.]

Jika sebuah bagian kosong, hapus judulnya. Bagian Diperbaiki yang kosong terbaca seolah tidak ada yang diperbaiki, dan judul tanpa apa pun di bawahnya membuat pembaca berpikir halamannya gagal dimuat.

Templat yang sama, sudah diisi

Beginilah tampilannya dengan konten nyata. Perhatikan tidak ada entri yang menyebutkan file, branch, nomor tiket, atau seseorang, dan perubahan yang merusak kompatibilitas dimulai dengan tindakan yang harus diambil pembaca.

## Acme API 4.2 - 20 Agustus 2026

Paginasi sekarang berbasis cursor di semua endpoint daftar.

### Perubahan yang merusak kompatibilitas
- `?page=` dihapus di semua endpoint daftar. Gunakan nilai
  `nextCursor` dari respons sebelumnya. `?page=` mengembalikan 400
  setelah 1 Oktober 2026. Langkah migrasi:
  acme.example/docs/pagination

### Baru
- Tampilan tersimpan di kotak masuk. Kunci satu filter sekali dan
  gunakan lagi dari sidebar.
- Webhook sekarang bisa dibatasi ke satu proyek saja.

### Ditingkatkan
- Endpoint daftar merespons sekitar empat kali lebih cepat di akun
  besar.
- Job ekspor sekarang melaporkan progres alih-alih terlihat macet.

### Diperbaiki
- Anggota yang diundang tidak lagi melihat dasbor kosong sebelum
  login pertama mereka.
- Stempel waktu di ekspor sekarang menghormati zona waktu akun.

Apa yang masuk di setiap bagian

Perubahan yang merusak kompatibilitas

Satu-satunya bagian dengan tenggat waktu di dalamnya. Katakan apa yang berhenti berfungsi, apa yang harus dilakukan sebagai gantinya, dan tanggal berhentinya. Jika kamu belum memutuskan tanggalnya, jangan publikasikan bagian ini dulu: perubahan yang merusak kompatibilitas tanpa tanggal dibaca sebagai mendesak, dan aliran urgensi palsu adalah cara orang belajar mengabaikan catatan rilismu.

Baru

Jelaskan hasilnya, bukan objek yang kamu bangun. Ujinya adalah apakah barisnya masih masuk akal bagi seseorang yang belum pernah melihat kodemu. "Tampilan tersimpan di kotak masuk" lolos. "Model SavedView dan migrasinya ditambahkan" tidak lolos.

Ditingkatkan

Kuantifikasi di mana kamu bisa dengan jujur. "Lebih cepat" hampir tidak berarti apa-apa dan pembaca mengabaikannya; "sekitar empat kali lebih cepat di akun besar" layak dibaca dan membangun ekspektasi yang bisa dimintai pertanggungjawaban. Jika tidak bisa mengukurnya, katakan apa yang lebih baik dengan cara yang bisa dibantah.

Diperbaiki

Tulis gejalanya, bukan penyebabnya. Pengguna mencari catatan ini untuk hal yang terjadi pada mereka, jadi "anggota yang diundang mendarat di dasbor kosong" bisa ditemukan dan "race condition di cache keanggotaan diperbaiki" tidak bisa.

Varian

Keempat bagian berlaku untuk sebagian besar rilis. Tiga kasus memerlukan perubahan:

• Rilis aplikasi mobile. App store menampilkan kolom yang-baru singkat, jadi mulailah dengan satu kalimat yang bisa dibaca orang di listing toko, lalu tautkan ke catatan lengkapnya. Review toko juga bisa menahan build selama berhari-hari, jadi beri tanggal catatan berdasarkan tanggal rilis, bukan tanggal merge.
• Rilis API. Beri versi catatan dengan cara yang sama kamu memberi versi API, dan cantumkan jendela deprecation di catatan itu sendiri, bukan hanya di dokumentasi. Konsumen API membaca catatan itu justru untuk mengetahui berapa lama waktu yang mereka miliki.
• Alat internal atau admin. Hilangkan bagian Ditingkatkan dan gabungkan ke Diperbaiki. Pengguna internal peduli apakah alur kerja mereka berubah, dan bagian Ditingkatkan yang panjang mengubur itu.

Empat aturan yang membuat ini tetap mudah dibaca

1. Tulis untuk seseorang yang tidak tahu kodemu. Tidak ada nama file, nama branch, ID tiket, nama layanan, atau nama kode internal.
2. Hilangkan apa pun yang tidak berdampak terlihat bagi pengguna. Pembaruan dependensi, refactor, perubahan CI, dan perbaikan salah ketik masuk ke riwayat commit, bukan catatan rilis. Cara paling umum catatan rilis mati adalah dengan dipenuhi pekerjaan yang tidak bisa dilihat siapa pun di luar tim.
3. Satu entri, satu perubahan. Jika satu baris butuh kata "dan" dua kali, itu mungkin dua entri.
4. Publikasikan dengan ritme yang bisa diandalkan orang, bahkan jika ritmenya adalah "kapan pun kami rilis". Catatan yang muncul empat kali dalam seminggu lalu tidak muncul selama dua bulan dianggap sebagai gangguan.

Format catatan rilis: bagian-bagiannya, secara berurutan

Formatnya kurang penting dibanding urutannya. Gaya judul apa pun yang kamu gunakan, pembaca yang menyurvei catatan rilis menginginkan empat hal yang sama dalam urutan yang sama, dan setiap format catatan rilis populer adalah variasi dari itu.

1. Judul yang mengatakan apa yang berubah bagi pembaca, bukan nomor versinya. Versinya masuk ke baris yang lebih kecil di bawahnya, dengan tanggal dalam bentuk ISO (2026-08-29) agar terbaca sama di setiap lokal.
2. Perubahan yang merusak kompatibilitas dan apa pun dengan tenggat waktu, lebih dulu, bahkan jika kecil. Jika pembaca berhenti setelah satu paragraf, inilah paragraf yang mereka butuhkan.
3. Apa yang baru, satu item per paragraf, dengan hasilnya di klausa pertama dan tindakan yang diperlukan, termasuk "tidak perlu tindakan", dinyatakan setiap kali.
4. Perbaikan dan peningkatan, lalu semua yang lain sebagai daftar satu baris di bagian bawah. Pembaruan dependensi dan perubahan internal tetap ada, karena satu orang yang mencarinya benar-benar membutuhkannya.

Di Markdown itu judul H2, baris versi dan tanggal yang redup, lalu bagian H3 untuk Merusak, Baru, Ditingkatkan, dan Diperbaiki. Di email itu urutan yang sama dengan judul sebagai subjek. Di widget changelog itu judul dan paragraf pertama, dengan sisanya di balik tautan. Templat di atas adalah bentuk itu yang dituliskan.

Untuk penulisannya sendiri, bukan bentuknya, lihat cara menulis catatan rilis yang benar-benar dibaca orang dan praktik terbaik catatan rilis yang layak dipertahankan di blog.

Pertanyaan umum

Seberapa panjang seharusnya catatan rilis?

Sepanjang yang dibutuhkan perubahan yang memengaruhi pengguna, dan tidak lebih. Rilis dengan satu perbaikan bug mendapat dua baris. Mengisi rilis kecil agar terlihat substansial melatih orang untuk melewati yang besar.

Apa bedanya catatan rilis dan changelog?

Dalam praktiknya istilah-istilah ini dipakai bergantian. Di tempat tim membedakannya, catatan rilis menjelaskan satu rilis dan ditulis untuk pengguna, sedangkan changelog adalah daftar berjalan setiap rilis sepanjang waktu. Templat ini mencakup satu rilis; changelog adalah yang kamu dapatkan saat menumpuknya dari yang terbaru.

Haruskah catatan rilis punya nomor versi?

Hanya jika penggunamu bisa melihatnya. Nomor versi berguna untuk API, library, dan software yang terpasang, di mana pembaca perlu tahu versi apa yang mereka pakai. Untuk aplikasi web yang di-deploy terus-menerus, tanggal lebih berguna, karena itulah yang bisa dicocokkan pengguna dengan pengalaman mereka.

Siapa yang seharusnya menulisnya?

Siapa pun yang tahu apa yang berubah, yang biasanya berarti engineer yang melakukan merge, diedit oleh siapa pun yang menguasai gaya bahasanya. Cara gagalnya jika ini diserahkan sepenuhnya ke seseorang di luar pekerjaan itu adalah catatan yang menjelaskan tiketnya alih-alih perubahannya.