Mengapa mengutip ID bug di catatan tempel dianggap praktik yang buruk?

28

Berdasarkan komentar dan peningkatan selanjutnya dari Bug dibuka kembali vs yang baru :

Mengutip ID bug di catatan tempel hanya .. sangat tidak ramah. - Krelp

Tampaknya setidaknya beberapa orang merasa bahwa merujuk ID bug di catatan tempel bukanlah ide yang baik. Saya pengembang yang cukup berpengalaman, jadi saya bertanya-tanya mengapa itu terjadi.

issue-tracking bug-report software-patches Travis Northcutt
sumber
27
tidak mengutip ID bug di catatan tempel hanya ... sangat tidak profesional. Jenis sampah seluruh titik memiliki pelacak masalah
nyamuk
Alasan yang sama bahwa memposting hanya tautan sebagai jawaban StackExchange tidak disukai - jika Anda hanya memposting tautan, di SE itu buruk karena (1) membutuhkan pengikut untuk mendapatkan penjelasan dan (2) mungkin menjadi tidak valid di masa depan jika tautan mati atau isinya berubah. Demikian pula, hanya memasukkan ID bug di catatan tempel (1) mengharuskan pergi ke pelacak bug untuk mendapatkan penjelasan dan (2) mungkin menjadi tidak valid di masa depan jika sistem pelacak bug berubah. Memasukkan tautan dalam jawaban SE atau ID bug dalam catatan tempel tidak masalah (dan sebenarnya merupakan praktik yang baik) sebagai tambahan untuk penjelasan reguler.
Ben Lee

Jawaban:

51

Menurut pendapat saya, ini adalah praktik yang baik, dengan asumsi pengguna Anda telah membaca akses ke database bug Anda. Ada banyak waktu di mana orang menunggu bug diperbaiki untuk memutuskan kapan harus memutakhirkan.

Saya pikir apa yang disukai adalah hanya mengutip bug id dan tidak ada lagi. Anda harus selalu memberikan deskripsi yang dapat dimengerti tanpa pergi ke pelacak bug. Itu juga memungkinkan Anda untuk mengganti pelacak bug di masa depan tanpa sepenuhnya membatalkan catatan rilis sebelumnya.

Karl Bielefeldt
sumber
Anda dapat mengutip melalui penyelesai referensi abstrak, alias redirect URL.
Donal Fellows
Seperti yang Anda katakan, bagian "Bug yang diperbaiki" (atau serupa) harus menyertakan Id dan judul sehingga pembaca tidak perlu mencari bug untuk memahami dengan tepat apa yang termasuk dan apa yang tidak.
StuperUser
5
@StuperUser - Id dan judul, minimal .
Oded
Yang menjengkelkan adalah menemukan notasi Bug ID hanya dalam komentar ketika sistem ID bug / persyaratan referensi tidak lagi digunakan.
jfrankcarr
14

Seperti yang dikatakan dalam komentar yang dikutip ... tidak ramah.

Tidak bersahabat dengan diri sendiri

Bayangkan skenario berikut. Anda melihat log dalam kontrol sumber. Anda bertanya-tanya apa komit berubah. Alih-alih menjelaskannya dalam bahasa Inggris biasa, ini memberi tahu Anda:

Dipecahkan # 1307

Anda menjalankan sistem pelacakan bug, berharap memiliki sesuatu yang bermanfaat. Bug # 1307 dilaporkan telah terpecahkan. Dalam deskripsi, Anda melihat:

Bug yang sama dengan # 1284

Terima kasih, ini sangat membantu. Anda sekarang harus menavigasi ke laporan bug # 1284 untuk membaca bahwa itu adalah duplikat bug # 1113 yang mengacu pada bug # 1112, # 1065 dan # 1067.

Lima menit kemudian, Anda tidak tahu apa yang Anda cari di awal.

Sebuah kontrol versi pesan log jauh lebih bermanfaat akan menjadi:

Mengatasi masalah dengan pengguna yang tidak dapat masuk dengan kata sandi lebih dari 25 karakter (lihat # 1307), dengan menghapus penerapan kebijakan panjang kata sandi yang sama ke lapisan akses data seperti yang digunakan di situs web itu sendiri.

Dengan cara yang sama, dalam sistem pelacakan bug, laporan # 1307 bisa lebih jelas , mengingat apa yang dimaksud dengan laporan bug # 1284, dan bagaimana yang baru berbeda dari yang lama.

Tidak bersahabat dengan pelanggan

Ini bukan satu-satunya masalah keramahan.

Yang kedua adalah bahwa dengan terlalu banyak merujuk tanpa info tambahan, Anda membuat catatan tempel / log kontrol versi / laporan sistem pelacakan bug tidak dapat digunakan oleh seseorang yang tidak terlalu mengenal sistem tersebut . Ketika Anda berurusan dengan sistem pelacakan bug setiap hari, Anda tahu cara cepat menavigasi melalui laporan, melihat beberapa laporan berdampingan, dll. Ketika Anda seorang pelanggan tanpa latar belakang teknis, Anda dapat dengan mudah hilang.

Sekali lagi, pesan yang lebih terperinci sangat membantu daripada sekadar referensi. Perhatikan bahwa Anda masih ingin menyimpan referensi: tidak ada yang lebih salah daripada bug yang sama dengan bug yang Anda temui dua minggu lalu, tetapi jangan ingat ID-nya.

Sebagai catatan, masalah yang sama ada di banyak yurisdiksi. Di Prancis misalnya, tidak jarang undang-undang merujuk ke banyak sumber, yang dapat berubah sementara itu. Ini berarti bahwa untuk benar-benar memahaminya, Anda harus menghabiskan waktu berjam-jam di perpustakaan, mencari lusinan teks yang dirujuk, masing-masing teks memiliki referensi sendiri kepada orang lain.

Arseni Mourzenko
sumber
5
Ini bukan masalah dengan dokumen rilis; ini masalah dengan tingkat detail dalam bug. Judul harus menggambarkan masalah aktual dan isi setiap bug memiliki Hasil yang Diharapkan dan Hasil yang Sebenarnya. Tidakkah bug seperti yang Anda jelaskan ditutup sebagai duplikat?
StuperUser
Berdasarkan hasil edit Anda. Anda telah mengutip Id dalam pesan Anda yang jauh lebih bermanfaat. Apakah yang Anda maksudkan dalam komentar asli Anda bahwa mengutip HANYA Id tanpa informasi lebih lanjut tidak membantu, sedangkan penjelasan yang tepat DAN ID membantu?
StuperUser
1
@StuperUser: persis. Memberikan penjelasan membantu orang-orang yang hanya ingin tahu tentang apa laporan komit / catatan tempel / bug, tanpa menghabiskan sepuluh menit membaca konten yang dirujuk. ID masih diperlukan untuk pelacakan dan orang-orang yang membutuhkan info yang sangat rinci, tepat, dan lengkap.
Arseni Mourzenko
2

Tidak ada yang salah dengan mengutip nomor masalah dalam catatan tempel, asalkan pengguna dapat membaca masalah yang dikutip. Jika database bug Anda memungkinkan siapa saja untuk membaca, mengutip nomor bug memang bisa sangat berguna. (Yang lebih baik, jika catatan tambalan Anda berada dalam format yang memungkinkan tautan, jadikan ID masalah itu menjadi tautan ke masalah yang dimaksud.) Ini tidak berarti bahwa Anda harus membuka semua masalah ke masyarakat umum; masih bisa bermanfaat untuk memiliki yang terselubung (misalnya, tempat mereka memasukkan kata sandi langsung!)

Mengutip nomor terbitan di mana orang yang membaca tidak dapat pergi dan mencari rincian dan riwayat bug, itu sangat tidak ramah. Bukan berarti mengutip masalah seperti itu tanpa ID masalah jauh lebih ramah.

Donal Fellows
sumber
"di mana orang yang membaca tidak bisa pergi dan melihat detailnya" sebagai orang yang telah menjadi orang seperti itu , saya tidak akan menyebut ini benar-benar tidak ramah. Saya memang menggunakan ID masalah untuk berkomunikasi dengan tim pendukung / pengembang yang pada gilirannya memiliki akses ke pelacak masalah. Fakta bahwa itu tidak terlihat oleh saya secara pribadi hanyalah gangguan kecil
nyamuk
2

Ini jelas tergantung siapa orang yang akan membaca catatan tempel, dan target pengguna perangkat lunak.

Tetapi dalam kebanyakan kasus, sebagian besar pengguna Anda tidak peduli tentang apa ID bug itu. Mereka tidak peduli mengapa itu rusak, apa perbaikannya, atau apa pun - mereka hanya ingin tahu apa yang berubah dengan deskripsi tekstual yang sangat ringkas tanpa harus pergi ke halaman lain untuk setiap perubahan.

Mengutip ID bug membuat saya berhenti dan berpikir, dan saya - sebagai pengguna - tidak mau berpikir. Ini semacam masalah kegunaan.

Lihatlah misalnya pada log perubahan Visual Assist X . Semua ID bug yang ditautkan itu hanyalah derau yang mengalihkan perhatian saya dari memahami apa yang berubah. Dan ini merupakan tambahan untuk Visual Studio, yang menargetkan programmer. Dan saya seorang programmer. Jika ini menggangguku, bayangkan rata-rata pengguna yang bahkan tidak tahu apa itu pelacak bug ..

PS: Saya adalah penulis komentar yang memicu pertanyaan

Thomas Bonini
sumber
1
Jujur saya menemukan dokumentasi di akhir tautan itu bermanfaat. Dimulai dengan ringkasan dan kemudian mengarahkan saya ke detail. Microsoft sering melakukan penautan yang serupa dalam artikel KB, bukan karena mereka melakukannya menjadikannya praktik yang baik, tetapi tentu saja tersebar luas dan tampaknya memberikan nilai bagi banyak pengguna.
Joshua Drake
1

ID bug wajib untuk titik referensi . Alasan:

  • Cegah ambiguitas: Dua bug atau lebih mungkin memiliki deskripsi serupa. Jadi seseorang perlu jangkar untuk membedakannya.
  • Kemudahan : Saat membahas bug, baik dengan pelanggan atau secara internal, ID bug sering digunakan sebagai formulir singkat. Jika ID akan dihilangkan dari catatan tempel, akan sulit untuk membahasnya:

3052 sudah diperbaiki, masih bekerja pada 3077

lebih nyaman daripada:

"Aplikasi crash pada tombol apply" telah diperbaiki, masih bekerja pada "NullReferenceException pada mengklik perubahan pengguna"

KMoraz
sumber
(1) Apa yang mencegah Anda menggabungkannya, seperti yang disarankan oleh MainMa? (2) Mengapa Anda melakukan satu setengah bug yang diperbaiki? Mengapa Anda tidak melakukan setelah 3052 diperbaiki, bahkan sebelum Anda mulai bekerja pada 3077?
JensG
0

Saya akan mengatakan itu tergantung pada sistem Anda: Saya beruntung bahwa yang saya gunakan secara otomatis mendeteksi referensi tersebut dalam pesan komit dan menambahkan tautan ke tiket yang disimpan dalam pelacak bug, jadi itu bukan masalah.

Tetapi jika saya berada di sistem di mana itu tidak tersedia, saya masih menyebutkan ID tiket (dengan cara itu Anda dapat dengan cepat mencari log dengan ID tiket ) bersama dengan deskripsi singkat tentang apa bug itu.

wildpeaks
sumber