Praktik terbaik release notes yang layak dipertahankan
5 menit baca diperbarui
Praktik terbaik release notes yang penting adalah yang punya konsekuensi terlampir: tulis entri saat merge, sebutkan siapa yang terdampak, nyatakan tindakan yang diperlukan bahkan jika tidak ada, beri tanggal pada breaking change, pertahankan satu entri permanen per perubahan, kelompokkan berdasarkan hasil, dan pertahankan bagian yang membosankan. Masing-masing mengubah apa yang dilakukan pembaca. Sebagian besar saran lain tentang topik ini mengubah tampilan catatan.
Cari praktik terbaik release notes dan Anda mendapatkan saran gaya: jelas, ringkas, gunakan bahasa sederhana, tambahkan screenshot. Tidak ada yang salah dari itu semua dan tidak ada yang mengubah apa pun, karena tidak ada tim yang pernah duduk dengan niat menjadi tidak jelas. Praktik di bawah ini disertai dengan biaya melewatkannya, karena praktik tanpa mode kegagalan terlampir hanyalah preferensi.
| Praktik | Biaya melewatkan |
|---|---|
| Menulis entri saat merge, bukan saat rilis | Entri yang direkonstruksi kemudian mengatakan “berbagai peningkatan” |
| Menyebutkan siapa yang terdampak | Setiap pembaca memutuskan itu tidak berlaku untuknya |
| Menyatakan tindakan yang diperlukan, termasuk “tidak ada” | Empat puluh tiket dukungan yang identik, dan pembaca yang mengasumsikan yang terburuk |
| Memberi tanggal pada breaking change, bukan memversikannya | Tenggat waktu ditemukan setelah lewat |
| Satu entri permanen dan bisa ditautkan per perubahan | Tidak ada yang bisa menjawab “kapan ini berubah” |
| Mengelompokkan berdasarkan hasil, bukan sistem | Pembaca membutuhkan arsitektur Anda untuk menemukan bagian mereka |
| Mempertahankan bagian yang membosankan | Keamanan, kepatuhan, dan yang men-debug ketidakcocokan versi kehilangan sumber mereka |
Apa saja praktik terbaik untuk release notes?
Tulis entri saat Anda merge, bukan saat Anda rilis. Biaya melewatkan: orang yang merekonstruksi rilis dari riwayat commit bukan yang membuat perubahan, dan akan menebak niatnya. Entri yang ditulis dua minggu kemudian adalah yang mengatakan “berbagai peningkatan”.
Sebutkan siapa yang terdampak, dengan nama. “Tim di paket Business”, “siapa pun yang menggunakan API ekspor v1”, “instalasi self-hosted di Postgres 14”. Biaya melewatkan: setiap pembaca harus mencari tahu apakah itu berlaku untuknya, dan kebanyakan akan memutuskan tidak.
Nyatakan tindakan yang diperlukan, termasuk saat tidak ada. Biaya melewatkan: dukungan menjawab pertanyaan yang sama empat puluh kali, dan pembaca yang tidak bertanya berasumsi sesuatu diperlukan dan menundanya.
Beri breaking change tanggal, bukan nomor rilis. “Dihapus di v5” tidak berarti apa-apa bagi yang tidak tahu kapan v5 tiba. “Berhenti berfungsi pada 1 November” berarti hal yang sama untuk semua orang. Biaya melewatkan: tenggat waktu ditemukan setelah lewat. Apa yang termasuk itu, dan checklist untuk merilisnya, ada di apa itu breaking change.
Pertahankan satu entri permanen dan bisa ditautkan per perubahan. Email bukan arsip dan pesan Slack bukan referensi. Biaya melewatkan: tidak ada yang bisa menjawab “kapan ini berubah” enam bulan kemudian, termasuk Anda. Email tetap punya tugas, dibahas di template email update produk; ia menunjuk ke entri alih-alih menggantikannya.
Kelompokkan berdasarkan hasil, bukan sistem. Biaya melewatkan: pembaca harus menyimpan arsitektur Anda di kepala untuk mengetahui bagian mana yang relevan bagi mereka. Urutan yang mengikuti ini ada di cara menulis release notes.
Pertahankan bagian yang membosankan. Pembaruan dependensi dan perubahan internal tetap ada, di bawah, satu baris masing-masing. Biaya melewatkan: tim keamanan, peninjau kepatuhan, dan yang men-debug ketidakcocokan versi kehilangan satu-satunya sumber mereka. Entri yang paling sering salah di sini adalah perbaikan; release notes perbaikan bug menunjukkan cara menulisnya agar pembaca tahu apakah mereka perlu bertindak.
Apa saja praktik terbaik changelog, dan bagaimana bedanya?
Changelog adalah referensi, jadi praktiknya tentang kelengkapan dan struktur, bukan persuasi. Empat yang penting:
- Satu jenis entri tetap per baris. Added, Changed, Deprecated, Removed, Fixed, Security. Bukan gaya rumah, tapi filter: itu yang memungkinkan permintaan “hanya breaking change”. Konvensi Keep a Changelog adalah sumber yang biasa.
- Bagian belum rilis. Tempat entri hidup antara merge dan rilis. Ketiadaannya adalah alasan mengapa tim menulis entri terlambat.
- Tanggal ISO.
2026-08-28, bukan28/08/26, yang berarti dua hari berbeda tergantung pembaca. - Satu entri per perubahan, bukan per commit. Tiga commit yang memperbaiki satu bug adalah satu entri.
Kedua artefak dibandingkan secara menyeluruh di changelog vs release notes; versi singkatnya adalah praktik changelog melindungi kelengkapan dan praktik release notes melindungi perhatian. Release notes privat untuk pelanggan enterprise membahas versi ini yang baru muncul begitu pelanggan Anda tidak lagi semuanya berada di build yang sama: tujuan kelengkapan dan perhatian yang sama, tapi disesuaikan per akun alih-alih disiarkan ke semua sekaligus.
Tiga yang ternyata kultus kargo
Emoji sebagai jenis entri. Roket dan kunci pas bukan taksonomi. Terlihat rapi dan tidak bisa difilter, diurutkan, atau dibaca secara berguna oleh pembaca layar. Gunakan kata-kata, dan jika Anda menginginkan emoji, letakkan setelah kata.
Nomor versi semantik sebagai judul untuk produk yang di-hosting. Semver adalah janji tentang kompatibilitas API. Untuk produk SaaS di mana tidak ada yang memilih versinya, nomor versi di judul adalah pengarsipan internal yang menyamar sebagai berita. Simpan semver di changelog dan jangan masukkan ke pengumuman.
Menerbitkan sesuai jadwal terlepas dari konten. Catatan bulanan tanpa isi mengajarkan orang bahwa catatan Anda adalah kebisingan. Terbitkan saat ada sesuatu untuk disampaikan. Changelog mencakup sisanya.
Yang benar-benar sulit
Menjaga changelog dan pengumuman tetap selaras, tanpa menulis semuanya dua kali.
Kebanyakan tim mulai dengan satu halaman, membaginya saat audiens berbeda, lalu diam-diam membiarkan salah satunya membusuk, biasanya changelog, karena itu yang tidak punya tenggat waktu terlampir. Jalan keluarnya bersifat struktural, bukan disiplin: simpan entri sebagai data dengan jenis, tanggal, dan audiens, dan perlakukan kedua permukaan sebagai rendering dari itu. Rangkuman alat changelog kami mencakup apa yang tersedia untuk itu, termasuk alat yang kami saingi, dan halaman alternatif Beamer adalah perbandingan jujur terhadap widget tempat kebanyakan tim memulai.
Template release notes adalah tempat langkah seleksi berada begitu entri sudah ada.
Jika Anda hanya menerapkan satu hal
Tulis entri saat merge, dalam format tetap, dengan satu jenis. Setiap praktik lain di halaman ini menjadi lebih mudah begitu itu diterapkan, dan tidak ada yang bertahan tanpanya.
FAQ
Haruskah release notes punya screenshot? Hanya dari hal yang berubah, dalam penggunaan. Screenshot halaman pengaturan yang tidak pernah dikunjungi siapa pun menambah gulir, bukan informasi. Teks yang menyebutkan hasil dan pembaca yang terdampak mengalahkan gambar yang tidak menunjukkan keduanya.
Bagaimana cara menulis release notes untuk breaking change? Pertama tanggal, kedua pemanggil yang terdampak, ketiga tindakan yang diperlukan, keempat migrasi. Jangan pernah memulai dengan nomor versi. Bentuk lengkapnya, dengan contoh entri, ada di apa itu breaking change.
Haruskah release notes ditulis oleh engineering atau marketing? Disusun oleh insinyur yang membuat perubahan, saat merge, dan diedit oleh seseorang yang membacanya sebagai orang luar. Tidak ada satu pun yang sendirian menghasilkan catatan yang bisa ditindaklanjuti pelanggan.
Apa format ideal untuk release notes? Pertama item dengan tenggat waktu, lalu kemampuan baru, lalu peningkatan, lalu daftar satu baris masing-masing untuk sisanya. Template release notes adalah format itu sebagai halaman untuk diisi.
Klaim teknis dalam artikel ini belum ditinjau secara independen. Jika ada yang keliru, beri tahu kami dan kami akan memperbaikinya.