رفتن به محتوای اصلی
نوتوا

گزارش باگ استاندارد چگونه بنویسیم؟ قالبی که خطا را قابل تکرار کند

قالب گزارش باگ استاندارد شامل عنوان، محیط، مراحل بازتولید، رفتار واقعی و مورد انتظار، Evidence، تکرارپذیری و حریم خصوصی Log.

تصویر مفهومی گزارش باگ استاندارد چگونه بنویسیم؟ قالبی که خطا را قابل تکرار کند
نمای مفهومی مسیر اصلی قالب گزارش باگ؛ جزئیات اجرایی در متن و چک‌لیست مقاله آمده است.

گزارش باگ را با محیط و Build دقیق، پیش‌شرط، مراحل حداقل، Actual/Expected، تکرارپذیری و Evidence پاک‌سازی‌شده بنویسید.

گزارش باگ خوب به فرد دیگری امکان می‌دهد خطا را در محیط مشخص بازتولید، رفتار واقعی را با انتظار مقایسه و Evidence لازم را بدون حدس پیدا کند. عنوان باید مسئله را یکتا کند؛ مراحل حداقل، Version، تکرارپذیری و داده امن ضروری‌اند.

قالب گزارش باگ

عنوان: [عمل/شرط] باعث [رفتار واقعی] می‌شود
محیط: app/build, OS/browser/device, account/role, locale/timezone
پیش‌شرط:
داده آزمون غیرحساس:
مراحل بازتولید:
1.
2.
3.
نتیجه واقعی:
نتیجه مورد انتظار:
تکرارپذیری: x از y بار
اولین/آخرین نسخه شناخته‌شده:
Evidence: screenshot/video/log/request-id/time
اثر کاربر و workaround:
نمودار مفهومی ورودی، اجرا، کنترل و خروجی برای قالب گزارش باگ
ورودی را کوچک و قابل کنترل نگه دارید، روش را ثبت کنید و خروجی را با شاهد مستقل بسنجید.

عنوان قابل جست‌وجو

بد:

آپلود کار نمی‌کند

بهتر:

آپلود PNG بالای ۵ MB در Chrome Android روی ۹۹٪ متوقف می‌شود

Solution پیشنهادی را جای Problem ننویسید؛ ابتدا رفتار را ثبت کنید.

محیط و نسخه

حداقل موارد مرتبط:

  • Version/Build/commit؛
  • Production/Staging؛
  • Browser + version یا App version؛
  • OS/Device؛
  • Role/permission؛
  • Locale/timezone؛
  • Network/feature flag؛
  • زمان دقیق همراه timezone.

«آخرین نسخه» بعداً مبهم می‌شود؛ شماره دقیق ثبت کنید.

مراحل بازتولید حداقل

هر گام یک عمل قابل اجرا باشد:

پیش‌شرط: کاربر Editor و پروژه P1 باز است.
1. تب Files را باز کنید.
2. فایل sample-6mb.png را انتخاب کنید.
3. روی «افزودن فایل» بزنید.
4. تا پایان Progress صبر کنید.

Actual: Progress روی ۹۹٪ می‌ماند؛ Request ID ... با status ...
Expected: فایل یک‌بار ثبت و در فهرست نمایش داده شود، یا خطای قابل اقدام دیده شود.

گام‌های زائد را حذف، اما شرط ضروری را نگه دارید. اگر Intermittent است، نسبت ۳/۱۰ و Pattern را ثبت کنید.

Expected از کجا می‌آید؟

  • Acceptance criteria؛
  • Specification/design approved؛
  • رفتار نسخه سالم؛
  • قرارداد API؛
  • استاندارد Accessibility/security؛
  • توافق Product در صورت ابهام.

نظر شخصی را به‌عنوان انتظار قطعی ثبت نکنید؛ Source را Link کنید.

Evidence امن

مفید:

  • Screenshot/Video کوتاه؛
  • Console/network log؛
  • Stack trace؛
  • Request/correlation ID؛
  • Timestamp؛
  • فایل نمونه مینیمال؛
  • HAR فقط پس از پاک‌سازی.

Token، Password، Cookie، اطلاعات شخصی، متن مشتری و Secret را حذف/ماسک کنید. گزارش آسیب‌پذیری را در کانال امنیتی خصوصی بفرستید، نه Issue عمومی.

Severity و Priority را قاطی نکنید

  • Severity: شدت اثر فنی/کاربری؛
  • Priority: ترتیب رسیدگی با Context کسب‌وکار.

گزارش‌دهنده اثر، گستره و Workaround را می‌نویسد؛ تیم طبق Policy شدت/اولویت نهایی را تعیین می‌کند.

باگ غیرقابل بازتولید

نباید فوراً بسته شود. این موارد را جمع کنید:

  • تعداد/شرایط رخداد؛
  • Timestamp و ID؛
  • Telemetry/Log قابل اجازه؛
  • Environment delta؛
  • آخرین عمل قبل خطا؛
  • Recovery/Workaround؛
  • Plan برای Instrumentation.

Status را Needs info / Cannot reproduce yet بگذارید، نه ادعای نبودن باگ.

Duplicate یا چند باگ؟

قبل از ثبت جست‌وجو کنید. اگر Root cause/رفتار مستقل است، Issue جدا با Link بسازید. چند خطای نامرتبط در یک گزارش Triage و Closure را سخت می‌کند.

برای تعریف Acceptance از راهنمای نوشتن تسک روشن استفاده کنید. باگ را در تسک و شواهد حجیم/تحقیق را با Link کنترل‌شده در یادداشت ثبت کنید.

چک‌لیست قبل Submit

  • عنوان رفتار را یکتا توصیف می‌کند.
  • Duplicate جست‌وجو شده است.
  • Build و محیط دقیق‌اند.
  • پیش‌شرط و داده تست موجودند.
  • مراحل حداقل و شماره‌دارند.
  • Actual و Expected جدا هستند.
  • تکرارپذیری ثبت شده است.
  • Evidence زمان‌دار است.
  • Secret/PII حذف شده است.
  • اثر و Workaround روشن‌اند.

پرسش های متداول

اگر باگ فقط یک بار رخ داد ثبت کنیم؟

بله، با Timestamp، Environment، ID و شواهد؛ وضعیت تکرارپذیری را صادقانه مشخص کنید.

Log کامل را پیوست کنیم؟

فقط پس از حذف Token، Cookie، PII و Secret و طبق دسترسی مجاز؛ بخش مرتبط و زمان‌دار بهتر است.

Severity و Priority چه فرقی دارند؟

Severity شدت اثر است؛ Priority ترتیب رسیدگی با Context کسب‌وکار و ظرفیت تیم.

جمع‌بندی

قالب باگ را حول بازتولید بسازید: محیط دقیق، پیش‌شرط، مراحل حداقل، Actual/Expected و Evidence امن. ابهام را با Source و Telemetry مدیریت کنید و Severity را از Priority جدا نگه دارید.