گزارش باگ
گزارش باگ خوب یعنی باگی که زود درست میشود. این کلمهها تیتر خانههای فرم گزارش باگ در گیتهاب و ابزارهای مشابهاند؛ یاد بگیر در هر خانه چه بنویسی.
قدمهای شمارهدار با فعل امری؛ should برای انتظار
در «Steps to reproduce» هر قدم یک خط شمارهدار است که با فعل امری شروع میشود: «1. Open the page. 2. Click Save.» فاعل (you) نوشته نمیشود. برای expected behavior از should استفاده کن («The page should show an error») و برای actual behavior از زمان حال ساده («The page shows nothing»). همین تفاوتِ should و حال ساده، خودِ باگ را نشان میدهد.
هشت کلمهی این درس
bug report (باگ ریپورت): گزارش باگ
report یعنی گزارش. bug report متنی است که به سازندههای یک برنامه میگوید چه چیزی خراب است. گزارش خوب چهار تکه دارد: یک خلاصهی یکخطی، قدمهایی که باگ را دوباره میسازد، چیزی که انتظار داشتی و چیزی که واقعاً شد. بهعلاوهی نسخهی برنامه و سیستمعامل. «کار نمیکند» گزارش باگ نیست.
A good bug report saves the developer hours of guessing.
یک گزارش باگ خوب، چند ساعت حدس زدن را از دوش برنامهنویس برمیدارد.
feature request (فیچِر ریکوئِست): درخواست یک قابلیت تازه
feature یعنی قابلیت و request یعنی درخواست. feature request پیامی است که در آن از سازندهها میخواهی چیزی تازه به برنامه اضافه کنند. فرقش با گزارش باگ: آنجا چیزی خراب است، اینجا چیزی نیست و تو دلت میخواهد باشد. درخواست خوب اول مشکل تو را میگوید، بعد راه پیشنهادیات را؛ و مؤدبانه است، چون کسی به تو بدهکار نیست.
I opened a feature request for exporting results to CSV.
برای خروجی گرفتن از نتیجهها به شکل CSV، یک درخواست قابلیت ثبت کردم.
steps to reproduce (اِستِپس تو ریپرُدوس): قدمهایی که باگ را دوباره میسازد
step یعنی قدم و reproduce یعنی «دوباره تولید کردن». این بخش از گزارش باگ، قدمبهقدم میگوید چه کار کنیم تا همان خطا را ببینیم. مهمترین بخش گزارش است: برنامهنویس تا باگ را با چشم خودش نبیند، نمیتواند درستش کند. قدمها را شماره بزن، هر کدام را با یک فعل امری شروع کن و هیچ قدمی را «واضح» حساب نکن.
Please add the steps to reproduce so we can see the bug.
لطفاً قدمهای بازسازی را اضافه کن تا بتوانیم باگ را ببینیم.
expected behavior (اِکسپِکتِد بیهِیویِر): رفتاری که انتظار داشتی ببینی
expected یعنی «مورد انتظار» و behavior یعنی «رفتار». در گزارش باگ، این بخش میگوید به نظر تو برنامه باید چه کار میکرد. لازم است، چون گاهی چیزی که تو باگ میدانی از نظر سازنده درست است؛ با نوشتن انتظارت، این اختلاف زود معلوم میشود. با should بنویس: «The app should show an error».
The expected behavior is that the form shows an error message.
رفتار مورد انتظار این است که فرم یک پیام خطا نشان بدهد.
actual behavior (اَکچوال بیهِیویِر): رفتاری که واقعاً دیدی
actual یعنی «واقعی»: چیزی که در عمل اتفاق افتاد. این بخش از گزارش باگ میگوید برنامه بهجای کار درست چه کرد. فقط چیزی را بنویس که دیدی، نه حدست دربارهی دلیلش را؛ و پیام خطا را حرفبهحرف کپی کن. باگ همان فاصلهی میان expected و actual است.
The actual behavior is a blank page with no error.
رفتار واقعی، یک صفحهی خالی بدون هیچ خطایی است.
severity (سِوِریتی): شدت؛ میزان خرابیای که یک باگ میزند
severe یعنی «شدید» و severity یعنی «شدت». در گزارش باگ میگوید این مشکل چقدر آسیب میزند: از critical (برنامه بالا نمیآید یا داده از بین میرود) تا low (یک غلط املایی در یک دکمه). severity دربارهی خود باگ است و به اینکه چه زمانی درستش میکنیم کاری ندارد؛ آن یکی priority است.
The severity is high because users lose their saved work.
شدتش بالاست، چون کاربرها کار ذخیرهشدهشان را از دست میدهند.
priority (پرایوریتی): اولویت؛ اینکه کدام کار زودتر انجام شود
priority یعنی اولویت: چیزی که باید قبل از بقیه به آن برسی. در ابزارهای مدیریت کار، هر باگ یا وظیفه یک priority دارد که ترتیب انجام را نشان میدهد و معمولاً با P0 (همین الان) تا P3 (هر وقت شد) نوشته میشود. باگی که شدتش کم است میتواند اولویت بالا داشته باشد، مثل غلط املایی در اسم شرکت روی صفحهی اول.
Fixing the payment bug is our top priority this week.
درست کردن باگ پرداخت، اولویت اول ما در این هفته است.
attachment (اَتَچمِنت): پیوست؛ فایلی که همراه پیام میفرستی
attach یعنی «چسباندن» یا «وصل کردن»، و attachment چیزی است که وصل شده: فایلی که همراه ایمیل یا گزارش باگ میفرستی، مثل اسکرینشات، فایل لاگ یا یک نمونهی داده. در متن پیام حتماً بگو چه چیزی پیوست کردهای، تا خواننده بداند باید آن را باز کند.
The log file is in the attachment below.
فایل لاگ در پیوستِ پایین است.
یک گزارش باگ کامل
Bug report #214
Title: Cart total is wrong after removing an item
Steps to reproduce:
1. Add two items to the cart.
2. Remove one item.
3. Look at the total.
Expected behavior: The total should show the price of one item.
Actual behavior: The total still shows the price of two items.
Severity: high (users may pay too much)
Priority: P1
Attachment: cart-total.png
Version: 3.2.0, Chrome on Windows 11
گزارش باگ شمارهی ۲۱۴
عنوان: جمع سبد خرید بعد از حذف یک کالا غلط است
قدمهای بازسازی:
۱. دو کالا به سبد اضافه کن.
۲. یکی را حذف کن.
۳. به جمع کل نگاه کن.
رفتار مورد انتظار: جمع کل باید قیمت یک کالا را نشان بدهد.
رفتار واقعی: جمع کل هنوز قیمت دو کالا را نشان میدهد.
شدت: بالا (شاید کاربرها پول اضافه بدهند)
اولویت: P1
پیوست: cart-total.png
نسخه: 3.2.0، کروم روی ویندوز ۱۱