Release notes perbaikan bug: cara menulis entri yang berguna

Release notes perbaikan bug yang baik menjelaskan apa yang dilihat pengguna salah, bukan apa yang salah di kode. Setiap entri menyebut siapa yang terdampak, sejak kapan, apakah perbaikannya tuntas, dan apakah pembaca perlu melakukan sesuatu, meskipun itu hanya “tidak ada tindakan yang diperlukan”.

Kebanyakan tim menyalin satu baris dari pesan commit. Tabel di bawah menunjukkan enam penulisan ulang, dan bagian sesudahnya menjelaskan aturannya.

Bagaimana menulis entri perbaikan bug di release notes?

Mulai dengan gejala dalam kata-kata pengguna, lalu siapa yang terdampak dan sejak kapan, lalu status perbaikannya, lalu tindakannya. Satu atau dua kalimat biasanya cukup. Penyebab di kode milik pull request, tempat engineer akan mencarinya.

Pembaca memindai satu hal: “apakah ini saya?” Empat bagian mencakup hampir setiap entri:

1. Gejalanya. Apa yang muncul di layar, di respons API, atau di invoice. Kutip teks error jika ada, karena orang mencarinya.
2. Cakupannya. Paket, platform, versi API, atau bentuk data mana. “Akun dengan lebih dari 50.000 baris” bisa dicek. “Sebagian pengguna” tidak.
3. Rentang waktunya. Sejak rilis atau tanggal berapa, agar pembaca bisa menilai apakah hasil aneh kemarin adalah bug itu.
4. Tindakannya. Jalankan ulang, sinkronkan ulang, upgrade, hapus workaround, atau tidak sama sekali.

Jika pengguna membuat workaround, baris tindakan adalah tempat Anda memberi tahu bahwa mereka bisa menghapusnya.

Apa perbedaan antara release note dan changelog?

Changelog adalah catatan lengkap dan berkelanjutan tentang perubahan. Release notes adalah pesan terpilih yang ditulis ulang tentang satu rilis untuk orang yang sedang menentukan apakah mereka peduli. Untuk perbaikan bug, changelog mendaftar setiap perbaikan dan catatan memimpin dengan yang mungkin disadari pembaca.

Salah ketik di tooltip hanya masuk changelog. Tarif pajak yang salah di invoice masuk keduanya. Pembagian lengkapnya ada di changelog vs release notes, dan bentuk catatan yang baik ada di cara menulis release notes.

Keep a Changelog adalah konvensi yang praktis untuk sisi pencatatan. Ia menyediakan “Fixed” untuk perbaikan bug dan judul “Security” tersendiri untuk kerentanan, pembagian yang sama dengan yang dibuat artikel ini untuk pembaca.

Apakah perbaikan bug termasuk update?

Ya. Perbaikan bug mengubah produk, jadi merilisnya adalah sebuah update. Menurut semantic versioning, perbaikan yang kompatibel ke belakang adalah rilis patch, misalnya 4.2.0 ke 4.2.1.

Apakah pembaca harus melakukan sesuatu adalah pertanyaan terpisah, dan catatan harus menjawabnya. Perbaikan yang mengubah apa yang diamati pemanggil yang benar sudah mendekati breaking change, dan breaking changes menjelaskan di mana batasnya.

Kapan perbaikan mendapat entri sendiri, dan kapan menjadi perbaikan kecil?

Beri perbaikan entri sendiri ketika pengguna bisa saja menyadari bug itu, kehilangan waktu atau data karenanya, atau membuat workaround. Kelompokkan di bawah daftar singkat “Perbaikan kecil” ketika tidak ada orang di luar tim Anda yang bisa melihatnya. Nilai dari pengalaman pembaca, bukan ukuran diff.

Setiap baris dalam kelompok itu tetap harus mengatakan sesuatu: “Memperbaiki beberapa masalah UI” hanyalah placeholder.

Bagaimana menulis tentang regresi?

Sebutkan rilis yang memperkenalkannya, sebut itu regresi, dan beri rilis yang memperbaikinya. Orang yang terkena bug itu sudah tahu ada yang rusak, jadi pengakuan singkat dan langsung lebih berguna bagi mereka daripada kata-kata yang samar.

Misalnya: “Hasil pencarian untuk kueri yang mengandung tanda hubung kosong di 4.1.0. Ini sudah diperbaiki di 4.1.1. Jika Anda mengubah kueri untuk menghindari tanda hubung, Anda bisa mengembalikannya.”

“Meningkatkan keandalan pencarian” terbaca sebagai berkelit bagi siapa pun yang kehilangan satu sore karena bug itu. Jika penyebabnya masih dikonfirmasi, katakan, seperti yang dinyatakan panduan release notes darurat: jangan biarkan catatan terdengar lebih yakin daripada tim.

Bagaimana mengumumkan perbaikan keamanan?

Nyatakan tingkat keparahan dengan jelas, sebut versi yang terdampak dan versi yang memperbaikinya, katakan seberapa mendesak upgrade-nya, dan sertakan pengenal CVE jika ada. Terbitkan detail hanya setelah pengguna bisa bertindak atas perbaikan, mengikuti proses pengungkapan terkoordinasi ketika ada pelapor.

Urutannya penting: pelapor memberi tahu Anda secara privat, Anda merilis perbaikan, dan catatan publik terbit ketika pengguna bisa melindungi diri. Proses pengungkapan kerentanan terkoordinasi CISA mengoordinasikan pelaporan, analisis, dan pengungkapan publik kerentanan. Aturan CVE Numbering Authority mengatur bagaimana catatan CVE diberikan dan diterbitkan, dan di GitHub repository security advisory memungkinkan Anda menyusun advisory secara privat dan meminta pengenal.

Entri keamanan biasanya memuat empat fakta:

• Apa yang bisa dilakukan penyerang, dalam satu kalimat dan tanpa proof of concept.
• Versi yang terdampak, dan versi yang memperbaikinya.
• Seberapa mendesak: “upgrade hari ini” atau “upgrade pada rilis Anda berikutnya”.
• Apakah Anda pernah melihat eksploitasi, dan kredit untuk pelapor jika mereka setuju.

Jangan sertakan langkah eksploit.

Apa yang harus dikatakan catatan tentang perbaikan kehilangan data?

Sebutkan data apa yang terdampak, cara mengetahui apakah data Anda terkena, dan apakah bisa dipulihkan. “Tidak ada tindakan yang diperlukan” jarang benar di sini, dan pertanyaan pertama pembaca adalah “apakah data saya hilang”.

Entri yang berguna memberi kondisi yang menghilangkan data (“menghapus folder saat sinkronisasi berjalan”), rentang waktu saat itu mungkin terjadi, cara memeriksa (“buka Sampah dan cari item bertanggal 3 sampai 9 September”), dan jalur pemulihan. Jika data tidak bisa dipulihkan, katakan. Hubungi pelanggan yang terdampak secara langsung juga, karena release note tidak boleh menjadi satu-satunya tempat seseorang mengetahui datanya terkena.

Mengapa “Perbaikan bug dan peningkatan performa” adalah catatan yang buruk?

Kalimat itu tidak memberi pembaca apa pun untuk ditindaklanjuti dan menyembunyikan perbaikan yang sedang ditunggu seseorang. Pelanggan yang melaporkan crash tidak tahu apakah sudah diperbaiki, dan pelanggan dengan workaround tidak tahu apakah harus menghapusnya.

Ada dua alternatif yang jujur. Jika sebuah rilis tidak punya apa pun yang bisa disadari pembaca, jangan terbitkan catatan dan biarkan changelog menyimpan catatannya. Jika ada perbaikan, daftarkan dengan bahasa pembaca:

Sebelum:
  Perbaikan bug dan peningkatan performa.

Sesudah:
  Diperbaiki: ekspor CSV gagal untuk proyek tanpa tag.
  Diperbaiki: mode gelap menyembunyikan kursor di kotak komentar.
  Lebih cepat: dasbor terbuka lebih cepat untuk workspace
  dengan lebih dari 100 proyek.

Dari mana asal catatan perbaikan bug?

Asalnya dari pull request yang memperbaiki bug dan laporan yang memicunya. Jika kata-kata pelapor ikut bersama perbaikannya, separuh gejalanya sudah tertulis.

Permintaan fitur vs bug menjelaskan mengapa melabeli laporan dengan benar menentukan siapa pemiliknya. Di Changeloop, bug yang dilaporkan lewat widget menjadi GitHub issue berlabel bug, dan entri changelog disusun dari pull request yang di-merge lalu ditahan agar seseorang menyetujuinya sebelum terbit. Template release notes memberi bentuk entri yang sama untuk menulis manual: gejala, cakupan, rentang waktu, tindakan.

FAQ

Apa yang harus dimuat release notes perbaikan bug? Setiap entri harus menyebut gejala yang dilihat pengguna, siapa yang terdampak, sejak rilis atau tanggal berapa, apakah perbaikannya tuntas, dan apa yang perlu dilakukan pembaca, termasuk “tidak ada”.

Haruskah setiap perbaikan bug dicantumkan di release notes? Tidak. Cantumkan yang bisa disadari pengguna, yang membuang waktu mereka, atau yang mereka akali, dan kelompokkan perbaikan kosmetik atau internal di bawah daftar singkat “Perbaikan kecil”. Changelog menyimpan setiap perbaikan untuk siapa pun yang perlu mencarinya.

Bagaimana menulis release notes untuk bug yang Anda perkenalkan sendiri? Katakan itu regresi, sebut rilis yang memperkenalkannya dan rilis yang memperbaikinya, dan beri tahu pembaca apakah mereka boleh menghapus workaround. Pernyataan yang lugas terbaca lebih baik daripada kata-kata yang dihaluskan.

Bagaimana memeriksa release notes produk yang Anda pakai? Cari halaman changelog atau release notes yang ditautkan dari menu bantuan, footer, atau dokumentasi produk, atau di tab releases repositori untuk proyek open source.

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

Terkait di changeloop: Templat catatan rilis