İçeriğe geç

Bug raporu nasıl yazılır: geliştiricinin işine yarayan rapor

Düzeltilen bir bug raporu nasıl yazılır: net bir başlık, tam yeniden üretme adımları, beklenen ve gerçekleşen sonuç, ortam bilgileri ve kanıt.

Geliştiricinin üzerinde çalışabileceği bir bug raporu yazmak için önce sorunu yeniden üret. Sonra net, tek satırlık bir başlık; ortamı (URL, tarayıcı ve sürümü, işletim sistemi, hesap); bilinen bir başlangıç noktasından numaralı yeniden üretme adımlarını; beklenen sonucu ve hata mesajlarının tam hâliyle gerçekleşen sonucu yaz. Ekran görüntüsü ya da kayıt, konsol hataları ve başarısız ağ isteği gibi kanıtları ekle. Her rapora bir bug.

İyi bir raporun testi basit: sorunu hiç görmemiş bir geliştirici, sana hiçbir şey sormadan onu kendi makinesinde üretebilir mi? Evet ise bug muhtemelen hızlıca düzelir. Sorularla geri dönmek zorunda kalıyorsa, her gidip gelme bir güne mal olur. Alanları bir kontrol listesi olarak istiyorsan bug raporu şablonumuzu kopyala.

1. Yazmadan önce yeniden üret

Bug'ı ikinci kez oluşturmayı dene. Bunu yaparken önemli olabilecek ayrıntılara dikkat et:

  • Hangi hesabı ya da rolü kullandığın.
  • Hangi verinin işin içinde olduğu: belirli bir ürün, uzun bir isim, boş bir liste, büyük bir dosya.
  • Hangi adımların gerçekten gerekli olduğu. En kısa yolu bulmak için adımları birer birer çıkar.
  • Başka bir tarayıcıda ya da gizli pencerede olup olmadığı.

Her seferinde oluyorsa harika. Yalnızca bazen oluyorsa say: "10 denemede 4". Hiç yeniden üretemiyorsan yine de raporla ve bunu açıkça söyle.

2. Daha önce raporlanmış mı kontrol et

Takip aracında hata mesajını, sayfanın adını ve birkaç anahtar kelimeyi ara. Bir eşleşme bulursan yeni bir kayıt açmak yerine ayrıntılarını ona ekle: ortamını, sorunu tetiklemenin yeni bir yolunu ya da en son build'de hâlâ olduğunu. Mükerrer kayıtlar bilgiyi kayıtlar arasında böler ve triyaj zamanını boşa harcar.

3. Net bir başlık yaz

Başlık, triyaj sırasında çoğu zaman insanların okuduğu tek şeydir. Özelliği değil, sorunu anlatsın.

Zayıf başlıkDaha iyi başlık
Giriş bozukSafari'de Google ile giriş, giriş sayfasına geri dönüp duruyor
Raporlarda bugSatış raporunun CSV dışa aktarımında 1.000'den sonraki satırlar eksik
Sayfa yavaşÇok faturası olan hesaplarda Faturalandırma sayfası 10 saniyeden uzun sürede yükleniyor
Kaydederken hataAdında emoji olan bir profili kaydetmek "Invalid input" döndürüyor

İşe yarayan bir kalıp: ne bozuk, artı ne zaman oluyor, artı nerede.

4. Ortamı anlat

Pek çok bug yalnızca belirli bir kurulumda ortaya çıkar. Şunları ekle:

  • Sorunun yaşandığı sayfanın URL'si.
  • Tarayıcı ve sürümü; örneğin Hakkında sayfasındaki sürüm numarasıyla Chrome, Firefox, Safari ya da Edge.
  • İşletim sistemi ve cihaz.
  • Yerleşim sorunuysa ekran boyutu.
  • Uygulama gösteriyorsa uygulama sürümü ya da build.
  • Hesap, rol ya da test kullanıcısı ve onunla ilgili özel her şey (deneme hesabı, büyük bir organizasyon, İngilizce olmayan bir dil ayarı).
  • Ekibin sunucu loglarında bulabilmesi için saat dilimiyle birlikte sorunun yaşandığı zaman.

5. Yeniden üretme adımlarını yaz

Adımlar raporun özüdür. İyi adımlar:

  • Bilinen bir durumdan başlar: "Admin olarak giriş yapılmış, Dashboard'da".
  • Numaralı her adımda tek bir eylem kullanır.
  • Tam veriyi belirtir: ürünü, dosyayı, yazdığın metni. Asla gerçek şifreler ya da kart numaraları koyma; test verisi kullan.
  • Geliştiricinin aynı düğmeyi bulması için uygulamada görünen etiketleri kalın ya da tırnak içinde kullanır.
  • Bug'ın ortaya çıktığı anda biter.
1. [email protected] olarak giriş yap (Admin rolü).
2. Ayarlar'a, ardından Ekip'e git.
3. "Üye davet et"e tıkla.
4. "[email protected]" gir ve "Görüntüleyici" rolünü seç.
5. "Davet gönder"e tıkla.

6. Beklenen ve gerçekleşen sonucu yaz

İkisini yan yana koy:

Beklenen: Davet Bekleyenler listesinde görünür ve bir onay bildirimi gösterilir.
Gerçekleşen: Diyalog kapanıyor, bildirim gösterilmiyor ve Bekleyenler listesi boş kalıyor.
             Sayfa yenilendikten sonra da davet hâlâ yok.

Neyin sebep olduğunu düşündüğünü değil, ne gözlemlediğini anlat. "Davet isteği başarısız oldu" bir çıkarımdır; "diyalog kapandı ve listede hiçbir şey görünmedi" ise bir gözlemdir. Bir hata mesajı gördüysen onu metin olarak, birebir kopyala. Geliştiriciler kodlarında tam olarak o metni arar.

7. Kanıt ekle

Kanıt, bir açıklamayı ispata dönüştürür ve çoğu zaman doğrudan nedeni gösterir.

  • Sorunlu bölgesi vurgulanmış ekran görüntüsü. İlgisiz kişisel verileri kırparak çıkar.
  • Hareket, zamanlama ya da birkaç adım içeren her şey için ekran kaydı. Kısa tut ve sorundan hemen önce başla.
  • Konsol hataları. Web uygulamalarında tarayıcı konsolundaki kırmızı bir hata çoğu zaman en faydalı ipucudur. Bkz. Chrome'da konsol logları nasıl dışa aktarılır.
  • Başarısız ağ isteği. Başarısız olan API çağrısının URL'si, durum kodu ve yanıt body'si. Bkz. Chrome'da ağ trafiği nasıl yakalanır.
  • Ekip ağ oturumunun tamamını isterse bir HAR dosyası. HAR dosyası nasıl alınır rehberini izle ve dosyayı önce HAR temizleyici ile temizle; çünkü HAR dosyaları çerezler ve token'lar içerir.

8. Etkiyi dürüstçe değerlendir

Ne kadar kötü olduğunu ve kaç kişiyi etkilediğini söyle. Varsa ekibinin önem derecesi ölçeğini kullan. Dürüst ol: her şey kritik olarak işaretlenirse hiçbir şey kritik değildir. Bir geçici çözüm bulduysan belirt; düzeltmenin ne kadar acil olduğunu değiştirir ve bu arada destek ekibine yardım eder.

9. Tek bir bug'la sınırlı tut

Aynı sayfada üç sorun bulduysan üç rapor yaz. Böylece her biri kendi başına atanabilir, düzeltilebilir, test edilebilir ve kapatılabilir. Birbiriyle ilgili görünüyorlarsa aralarında bağlantı kur.

10. Ulaşılabilir ol

Gönderdikten sonra kaydı sorular için takip et. Düzeltme yayına çıktığında aynı adımlarla yeniden test et ve onayla. Bug daha sonra geri gelirse asıl kaydı yeniden aç ya da ona bağlantı ver; böylece geçmiş tek bir yerde kalır.

Sık yapılan hatalar

  • "Çalışmıyor" ya da "sayfada sorun" gibi belirsiz başlıklar.
  • Eksik adımlar ya da bir akışın ortasından başlayan adımlar.
  • Hata mesajlarının metni yerine ekran görüntüsü; bunlar aranamaz.
  • Tek kayıtta birden çok bug.
  • Raporda gerçek gizli bilgiler: ekran görüntülerinde ve loglarda şifreler, API anahtarları, oturum çerezleri ya da müşteri verileri.
  • Duygusal dil. Sakin, olgulara dayanan bir rapor, öfkeli bir rapordan daha hızlı düzeltilir.

İyi ve kötü raporları yan yana görmek için bug raporu örneklerimize bak.

Daha az yaz, daha çok yakala

Bir bug raporundaki emeğin çoğu teknik ayrıntılara gider; bunlar aynı zamanda raporu yazanların unuttuğu kısımlardır. Ücretsiz bir Chrome eklentisi olan Midge, ekranını kaydeder ya da ekran görüntüsü alır ve bu ayrıntıları senin yerine ekler; sen yalnızca başlığı, adımları ve ne beklediğini yazarsın. Her kayıtta konsol logları, ağ istekleri, kullanıcı adımları ve cihaz bilgileri var. Şifreler, kart numaraları, token'lar ve çerezler, hiçbir şey cihazından çıkmadan önce tarayıcında maskelenir. Rapor, ekibinin kullandığı takip aracına yapıştırabileceğin tek bir bağlantı olarak paylaşılır.

İlgili rehberler

Sık sorulan sorular

Bir bug raporunun en önemli kısımları nelerdir?

Yeniden üretme adımları, beklenen sonuç ve gerçekleşen sonuç. Bu üçüyle bir geliştirici genellikle sorunu kendi gözüyle görebilir. Ortam bilgileri ve ekran görüntüleri ile konsol hataları gibi kanıtlar süreci hızlandırır.

Bir bug raporu ne kadar uzun olmalı?

Eksiksiz kalmak şartıyla olabildiğince kısa. İyi raporların çoğu tek bir ekrana sığar: tek satırlık bir başlık, kısa bir özet, beş ila on adım, beklenen ve gerçekleşen sonuç ve ekler.

Bug'ı yeniden üretemezsem ne olacak?

Yine de raporla ve bunu belirt. Tam olarak ne yaptığını ve ne zaman olduğunu anlat, elindeki ekran görüntüsü ya da konsol hatası gibi kanıtları ekle. Sıklığı "bir kez oldu" olarak işaretle.

Nedeni hakkındaki görüşümü eklemeli miyim?

Gözlemleri ve tahminleri ayrı tut. Ana alanlara ne gördüğünü yaz; bir teorin varsa onu, tahmin olduğunu belirterek bir notlar bölümüne ekle.