قالب گزارش باگ خوب: چه چیزی باید داخلش باشد

در این مقاله می‌خوانید

1. قالب
2. چرا هر بخش لازم است
3. عنوان
4. مراحل — مهم‌ترین بخش
5. انتظار در برابر واقعیت
6. تکرارپذیری
7. محیط
8. اسکرین‌شات
9. و حالا مشکل این قالب
10. چه چیزی را نباید بپرسید
11. چه چیزی فقط از کاربر برمی‌آید
12. یک نمونه، بد و خوب
13. وقتی گزارش از پشتیبانی می‌آید
14. دو قالب، نه یکی
15. چند نکتهٔ عملی
16. شدت و اولویت را قاطی نکنید
17. وقتی باگ «گاهی» رخ می‌دهد
18. قالب را در GitHub به فرم تبدیل کنید
19. پرسش‌های رایج
20. باگ است یا درخواست قابلیت؟
21. ویدئو بهتر است یا اسکرین‌شات؟
22. آسیب‌پذیری امنیتی را هم با همین قالب گزارش کنم؟
23. جمع‌بندی
24. منابع و مطالعهٔ بیشتر

گزارش باگی که نتوان بازتولیدش کرد، حل نمی‌شود. و بیشتر گزارش‌ها قابل بازتولید نیستند — نه به این دلیل که گزارش‌دهنده بی‌دقت است، بلکه چون کسی به او نگفته چه چیزی لازم است.

این مقاله یک قالب آماده است، به‌علاوهٔ توضیح اینکه هر بخش چرا آنجاست.

قالب

عنوان:
  [یک جمله: چه چیزی، کجا]

چه کردم:
  ۱.
  ۲.
  ۳.

چه انتظاری داشتم:

چه دیدم:

هر بار تکرار می‌شود؟  بله / نه / گاهی

محیط:
  مرورگر و نسخه:
  دستگاه:
  آدرس صفحه:

اسکرین‌شات: [پیوست]

چرا هر بخش لازم است

عنوان

باید در فهرست، بدون باز کردن، قابل فهم باشد. «مشکل در سایت» بی‌فایده است؛ «دکمهٔ ثبت سفارش در موبایل کار نمی‌کند» در یک نگاه اولویت را مشخص می‌کند.

مراحل — مهم‌ترین بخش

«روی ذخیره زدم و ارور داد» قابل بازتولید نیست. آنچه لازم است:

۱. با حساب کاربری عادی وارد شدم
۲. به صفحهٔ ویرایش پروفایل رفتم
۳. فیلد ایمیل را خالی کردم
۴. روی «ذخیره» زدم

معیار خوب بودن: آیا کسی که سیستم را نمی‌شناسد می‌تواند فقط با خواندن این‌ها، همان نتیجه را بگیرد؟

انتظار در برابر واقعیت

این دو خط گاهی معلوم می‌کنند که اصلاً باگی در کار نبوده و انتظار اشتباه بوده — که خودش یافتهٔ ارزشمندی است، چون یعنی رابط کاربری گیج‌کننده است.

تکرارپذیری

یک کلمه که مسیر تحقیق را کاملاً عوض می‌کند. «هر بار» یعنی باگ منطقی است. «گاهی» یعنی احتمالاً مسئلهٔ زمان‌بندی یا وابسته به داده است — و توسعه‌دهنده از همان ابتدا جای دیگری را می‌گردد. انواع باگ را در باگ نرم‌افزاری چیست؟ دسته‌بندی کرده‌ایم.

محیط

بخش بزرگی از باگ‌ها مخصوص یک مرورگر یا یک اندازهٔ صفحه‌اند. بدون این اطلاعات، توسعه‌دهنده روی کروم دسکتاپ تست می‌کند، مشکلی نمی‌بیند، و گزارش را می‌بندد. این یکی از دلایلی است که باگ‌ها فقط در production ظاهر می‌شوند.

اسکرین‌شات

تفاوت بین توصیف و شواهد. یک تصویر معمولاً چیزی نشان می‌دهد که گزارش‌دهنده اصلاً به آن اشاره نکرده بود.

و حالا مشکل این قالب

اگر این قالب را جلوی کاربر عادی بگذارید، اکثریت قاطعشان پرش نمی‌کنند. هشت فیلد برای کسی که فقط می‌خواست خریدش را تمام کند، خیلی زیاد است. نتیجه: فقط عصبانی‌ترین کاربران گزارش می‌دهند و بازخوردی که می‌گیرید نمایندهٔ بقیه نیست. چرا کاربران باگ گزارش نمی‌دهند دقیقاً همین را بررسی می‌کند.

راه‌حل این نیست که قالب را کوتاه کنید و اطلاعات کمتری بگیرید. راه‌حل این است که بیشتر فیلدها را خودتان پر کنید. این همان اصلی است که در چطور از کاربران بازخورد واقعی بگیریم گفتیم: زمینه را خودتان جمع کنید، نه از کاربر.

چه چیزی را نباید بپرسید

نرم‌افزار شما این‌ها را از قبل می‌داند و پرسیدنشان فقط اصطکاک است:

• مرورگر و نسخه‌اش
• دستگاه و اندازهٔ صفحه
• آدرس صفحه
• خطاهای کنسول در همان لحظه
• مسیری که کاربر تا اینجا طی کرده
• اسکرین‌شات — می‌شود خودکار گرفت
• هویت کاربر، اگر وارد حساب شده

چه چیزی فقط از کاربر برمی‌آید

• چه کاری می‌خواست بکند
• چه انتظاری داشت

یعنی قالب واقعی برای کاربر نهایی، همین دو مورد است — و در عمل معمولاً یک کادر متن کافی است. بقیه را سیستم ضمیمه می‌کند.

یک نمونه، بد و خوب

تفاوت را در عمل ببینید. همان باگ، دو گزارش:

گزارش بد:

عنوان: سایت خرابه
متن: نمیشه سفارش داد لطفا درست کنید

توسعه‌دهنده چه می‌داند؟ تقریباً هیچ. باید بپرسد کدام صفحه، کدام مرورگر، چه کردید، چه دیدید — و هر سؤال یک روز رفت‌وبرگشت است.

گزارش خوب:

عنوان: دکمهٔ «ثبت سفارش» در موبایل هیچ واکنشی ندارد

چه کردم:
  ۱. با گوشی وارد سایت شدم (سافاری، آیفون)
  ۲. یک محصول به سبد اضافه کردم
  ۳. به صفحهٔ تسویه رفتم و فرم را پر کردم
  ۴. روی «ثبت سفارش» زدم

انتظار داشتم: به درگاه پرداخت برود
دیدم: هیچ اتفاقی نمی‌افتد، دکمه فقط کمی تیره می‌شود

هر بار تکرار می‌شود؟ بله، سه بار امتحان کردم
روی لپ‌تاپ همان حساب کار می‌کند

مرورگر: Safari، iOS 17
آدرس: example.com/checkout
[اسکرین‌شات پیوست]

این گزارش تقریباً خودش تشخیص را می‌دهد: مشکل مخصوص سافاری موبایل است، در مرحلهٔ ارسال فرم، و تکرارپذیر. توسعه‌دهنده می‌تواند مستقیم سراغ همان مسیر برود.

تفاوت این دو، تفاوت بین چند روز و چند ساعت است — و نکتهٔ مهم اینکه گزارش‌دهندهٔ دوم لزوماً فنی‌تر نیست؛ فقط قالبی جلویش بوده که می‌گفت چه چیزی لازم است.

وقتی گزارش از پشتیبانی می‌آید

مسیر رایج در بیشتر تیم‌ها: کاربر به پشتیبانی می‌گوید، پشتیبانی به توسعه. اینجا اطلاعات در هر انتقال کم می‌شود.

سه کار این نشتی را کم می‌کند:

• به پشتیبانی چک‌لیست بدهید — همان قالب، ولی به‌عنوان سؤال‌هایی که موقع صحبت با کاربر بپرسد.
• عین جملات کاربر را نگه دارید. ترجمهٔ «گفت دکمه کار نمی‌کند» به «باگ در فرم ثبت» ممکن است اطلاعات مهمی را حذف کند.
• مسیر مستقیم هم باز بگذارید. بعضی کاربران ترجیح می‌دهند خودشان گزارش دهند تا اینکه با پشتیبانی حرف بزنند — و گزارش مستقیم آن‌ها معمولاً دقیق‌تر است.

دو قالب، نه یکی

اشتباه رایج این است که یک قالب برای همه بگذارید. دو مخاطب متفاوت دارید:

کاربر نهایی: یک کادر متن، اسکرین‌شات خودکار، و تمام. هر فیلد اضافه، درصدی از گزارش‌ها را حذف می‌کند.

تیم داخلی و تستر: قالب کامل بالا. این‌ها می‌دانند چرا هر فیلد لازم است و پر کردنش برایشان بخشی از کار است.

چند نکتهٔ عملی

یک باگ در هر گزارش. گزارشی که سه مشکل را با هم می‌آورد، یا ناقص حل می‌شود یا معلوم نیست کِی باید بسته شود.

حدس علت را جدا کنید. «فکر کنم مشکل از کش است» ممکن است کمک کند، ولی گاهی توسعه‌دهنده را به مسیر اشتباه می‌برد. اگر می‌نویسید، صریح بگویید که حدس است.

گزارش‌های تکراری بد نیستند. اگر پنج نفر یک چیز را گزارش کردند، این خودش داده است: یعنی مشکل گسترده است. آن‌ها را به هم وصل کنید، نه اینکه با دلخوری ببندید.

شدت و اولویت را قاطی نکنید

اگر به قالب داخلی فیلد «اهمیت» اضافه می‌کنید، بدانید که دو معنا دارد و بهتر است جدا بمانند.

شدت (severity) یعنی باگ چه آسیبی می‌زند. این را گزارش‌دهنده می‌تواند توصیف کند، چون اثرش را دیده. اولویت (priority) یعنی کِی باید درست شود. این تصمیم تیم است، چون به چیزهایی بستگی دارد که گزارش‌دهنده نمی‌بیند: چند کاربر درگیرند، چه کار دیگری در صف است، و آیا راه دور زدنی هست.

این دو همیشه هم‌جهت نیستند. غلط املایی در نام شرکت روی صفحهٔ اول شدت کمی دارد، ولی اولویتش می‌تواند بالا باشد. گزارشی در پنل مدیریت که سالی یک بار استفاده می‌شود و کامل از کار افتاده، شدت بالایی دارد، ولی اگر تا موعدش ماه‌ها مانده، می‌تواند صبر کند.

برای اینکه شدت سلیقه‌ای پر نشود، تعریف هر سطح را کنار قالب بنویسید. چهار سطح برای بیشتر تیم‌ها کافی است:

• بحرانی — کار اصلی محصول متوقف شده یا داده از دست می‌رود، و راه دور زدنی نیست. مثلاً هیچ‌کس نمی‌تواند پرداخت کند.
• جدی — قابلیت مهمی برای گروهی از کاربران کار نمی‌کند، یا راه دور زدنش برای کاربر عادی معلوم نیست.
• متوسط — مشکل واقعی است ولی راه دور زدن ساده‌ای دارد.
• جزئی — ظاهری یا متنی؛ کار کسی را متوقف نمی‌کند.

کلید این مقیاس سؤال «راه دور زدن هست؟» است. وقتی جوابش در گزارش آمده باشد، اولویت‌بندی بر پایهٔ واقعیت پیش می‌رود، نه صدای بلندتر.

وقتی باگ «گاهی» رخ می‌دهد

در باگی که فقط گاهی تکرار می‌شود، مراحل به‌تنهایی کافی نیستند: با همان مراحل، بار دوم همه‌چیز درست کار می‌کند. این‌ها را هم به گزارش اضافه کنید:

• زمان دقیق، با ساعت و دقیقه. این پل بین گزارش و لاگ‌های سرور است؛ توسعه‌دهنده با آن می‌تواند همان درخواست را پیدا کند.
• نسبت تکرار. «از ده بار، سه بار» خیلی بیشتر از «گاهی» می‌گوید.
• تفاوت دفعه‌های خراب و سالم. حساب کاربری دیگر؟ اینترنت همراه به‌جای وای‌فای؟ روشن بودن VPN؟ سبد خرید با یک کالا یا ده کالا؟ گزارش‌دهنده لازم نیست علت را بداند؛ فقط آنچه فرق داشته را بنویسد.
• متن دقیق پیام خطا، کپی‌شده نه بازنویسی‌شده. اگر پیام کد یا شناسه‌ای دارد، همان از همه مهم‌تر است.

باگی که فقط یک بار دیده شد را هم با برچسب «یک بار» و زمان دقیق گزارش کنید. وقتی گزارش دوم و سوم با همان نشانه رسید، الگو معلوم می‌شود.

قالب را در GitHub به فرم تبدیل کنید

قالبی که فقط در یک سند نوشته شده، زود فراموش می‌شود. اگر تیمتان از GitHub استفاده می‌کند، با issue form می‌توانید همان قالب را به فرمی تبدیل کنید که فیلدهای اجباری دارد و بدون پر کردنشان ثبت نمی‌شود. فایلی در مسیر .github/ISSUE_TEMPLATE/bug_report.yml بسازید:

name: گزارش باگ
description: مشکلی را که دیده‌اید گزارش کنید
title: "[باگ] "
labels: ["bug"]
body:
  - type: textarea
    id: steps
    attributes:
      label: چه کردم
      description: مراحل را از ابتدا و شماره‌دار بنویسید.
      placeholder: |
        ۱.
        ۲.
        ۳.
    validations:
      required: true
  - type: textarea
    id: expected
    attributes:
      label: چه انتظاری داشتم
    validations:
      required: true
  - type: textarea
    id: actual
    attributes:
      label: چه دیدم
    validations:
      required: true
  - type: dropdown
    id: reproducible
    attributes:
      label: هر بار تکرار می‌شود؟
      options:
        - بله
        - گاهی
        - فقط یک بار دیدم
    validations:
      required: true
  - type: input
    id: environment
    attributes:
      label: مرورگر، دستگاه و آدرس صفحه
  - type: textarea
    id: logs
    attributes:
      label: متن خطا یا لاگ
      render: shell

دو جزئیات مفید: «تکرارپذیری» کشویی است تا پاسخ‌ها یکدست باشند و بشود بر اساسشان فیلتر کرد، و render: shell باعث می‌شود متن خطا یا لاگی که چسبانده می‌شود، به‌صورت کد نمایش داده شود و به‌هم نریزد. اگر تازه تست نرم‌افزار را در تیم شروع کرده‌اید، از روز اول گزارش تسترها را از همین مسیر بگیرید.

پرسش‌های رایج

باگ است یا درخواست قابلیت؟

اگر نرم‌افزار کاری را که قرار بوده بکند نمی‌کند، باگ است. اگر همان کاری را می‌کند که طراحی شده ولی شما رفتار دیگری می‌خواهید، درخواست قابلیت است. مرزش همیشه روشن نیست، و همین‌جاست که بخش «انتظار در برابر واقعیت» به کار می‌آید: با همان قالب بنویسید و دسته‌بندی را به تیم بسپارید.

ویدئو بهتر است یا اسکرین‌شات؟

برای مشکلی که در یک حالت ثابت دیده می‌شود — متن به‌هم‌ریخته، پیام خطا — اسکرین‌شات کافی است. برای مشکلی که در جریان چند قدم رخ می‌دهد، مثل دکمه‌ای که با دو بار کلیک سفارش تکراری ثبت می‌کند، یک ضبط کوتاه صفحه خیلی بیشتر می‌گوید. ولی ویدئو جای مراحل نوشتاری را نمی‌گیرد، چون متن را می‌شود جست‌وجو کرد و قدم‌به‌قدم دنبال کرد. در هر دو حالت، رمز، شمارهٔ کارت و اطلاعات مشتری را پیش از ارسال بپوشانید.

آسیب‌پذیری امنیتی را هم با همین قالب گزارش کنم؟

ساختارش همین است — مراحل، انتظار، نتیجه — ولی مسیرش نه. آسیب‌پذیری را هرگز در issue عمومی یا گروه چت ننویسید؛ تا رفع نشده، هر کسی که آن را بخواند می‌تواند از آن سوءاستفاده کند. از کانال خصوصی‌ای استفاده کنید که سازنده برای این کار معرفی کرده، مثل فایل SECURITY.md در مخزن یا یک نشانی ایمیل امنیتی. دنیای باگ‌هانتینگ قواعد خودش را برای این نوع گزارش دارد.

جمع‌بندی

یک گزارش باگ خوب به دو سؤال پاسخ می‌دهد: چطور دوباره ایجادش کنم، و چقدر مهم است. هرچه بیشتر از پاسخ این دو را خودکار جمع کنید، گزارش‌های بیشتری می‌گیرید و هر کدامشان قابل استفاده‌تر است.

و معیار نهایی ساده است: اگر توسعه‌دهنده مجبور شود برای فهمیدن گزارش به گزارش‌دهنده پیام بدهد، آن قالب کارش را انجام نداده است.

منابع و مطالعهٔ بیشتر

• راهنمای نوشتن گزارش باگ موزیلا — مراحل بازتولید، انتظار و نتیجه
• How to Report Bugs Effectively — سایمن تاتام — چرا «کار نمی‌کند» کافی نیست
• قالب issue در GitHub — ساختن قالب گزارش برای تیم داخلی