چطور در GitHub issue گزارشِ خوب بنویسم؟

همان فرمولِ چهاربندی + عنوانِ رفتاری: نهِ «Bug!!!»، که **"Checkout total shows 0 when discount code is applied"**. اضافهها: لاگ و اسکرینشات (code block با ```), نسخهها (browser, OS, app version), و **severity**: «Blocks checkout for ~5% of users — high priority.» الگوی رایجِ متنِ باز: تیکهٔ «Environment» و «What I've tried» — نوشتنِ «چه کردم»، دوستِhelpers است.

«prod is down» واقعاً پیش میآید؟ چه بگویم؟

میآید — و برایش درسِ جدا داریم (۸۲: incident). پیشنمایشِ جملههای بحرانی: اعلام (Pagers are going off — checkout is down), دعوت (Starting a bridge call — join if you can), وضعیت (It's regional, only EU. Rollback is running), و تثبیت (Traffic is back. Writing the postmortem). آرامشِ این جملهها در فاز ۵ کامل میشود — فعلاً ساختار را بشناس که روزِ سخت، غافلگیر نشوی.

درس ۵۷ از ۹۰ · دیباگ به انگلیسی؛ توصیفِ مشکل، فرضیه‌سازی و «found it!»

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

این درس علاوه بر جمله‌ها، فرمولِ گزارشِ باگ را می‌دهد که در Jira و GitHub issue هم همان است — یعنی سرمایه‌گذاریِ یک‌بار و بازدهیِ هرروزه.

توصیفِ دقیق؛ گزارشی که خودش نصفِ حل است

فرمولِ گزارشِ کامل: ۱) انتظار vs واقعیت: "Checkout should show the total, but it shows zero." ۲) بازسازی: "Steps to reproduce: add two items, apply the discount code, go to checkout — total is zero." ۳) دامنه: "Only on production, only for logged-in users. Staging is fine." ۴) زمان: "Started after yesterday's release — worked fine before." — همین چهار بند، ۸۰٪ سوال‌های اولیهٔ helpers را جواب می‌دهد و به آن‌ها «شروعِ گرم» می‌دهد. واژه‌ها: reproduce (بازسازی), expected behavior (رفتارِ موردِ انتظار), actual behavior (رفتارِ واقعی), consistent / intermittent (همیشه / گاهی‌به‌گاه — باگِ بی‌ثبات را intermittent بگو، خدایانِ دیباگ قربانی می‌خواهند: flaky برای تست‌ها).

It's intermittent — maybe one in ten requests. I can't reproduce it on demand, but here's a log snippet from the last time it happened.گاهی‌به‌گاهه — شاید یک در ده درخواست. به‌دست نمی‌آیدش بازسازی کنم، ولی این تکه‌لاگِ دفعهٔ قبلشه.

فرضیه‌سازی؛ بلند فکرکردنِ منظم

قالب‌های فرضیه: "My theory is the cache is stale — the config changed but the TTL is long." · "I suspect a race condition: two workers pick the same job." · "It's either the token expiring or the clock drift — let me check the logs." (It's either A or B — قالبِ دوگانهٔ شکار) و مراحلِ حذف: "I've ruled out the network — same behavior on localhost." (شبکه رو حذف کردم — روی لوکال هم همینه.) زبانِ حذفِ گزینه‌ها، به تیم نشان می‌دهد که شکارِ سیستماتیک در جریان است نه گیرزدنِ کور.

Working theory: the migration left the old index in place, and the query planner picks it. Dropping it should fix the slow queries.فرضیه: مایگریشن ایندکسِ قدیمی رو گذاشت و پلنِ کوئری همونو برمی‌داره. حذفش باید کوئری‌های کند رو درست کنه.

کمک‌خواهی و جمع‌بندی؛ جامعهٔ شکار

کمک‌خواهیِ هدفمند: "Has anyone seen this error before? Connection reset by peer — first time for me." · "Jack, you know the payments service best — got 10 minutes to pair on this?" و جمع‌بندیِ دو حالت — پیروزی: "Found it! The discount was applied twice — fixing now, PR in 30 minutes." (پیداش کردم! تخفیف دوبار اعمال می‌شد — الان درستش می‌کنم، PR تا ۳۰ دقیقه) و شکستِ موقت: "No luck today. I've narrowed it to the webhook handler. Picking it up fresh tomorrow." — هر دو، جمله‌هایِ حرفه‌ایِ پایانِ شیفتِ شکارند. و بعد از فیکس: "Added a regression test so it never happens again." — بستنِ حلقه، امضای مهندسِ بزرگ.

گرامرِ عمیق‌تر: زبانِ حدس و حذف — might و must و رِجاکسیسم

دیباگ، گرامرِ احتمال دارد: might (شاید — احتمالِ ضعیف), could (ممکن است — امکان), must (حتماً — استنتاجِ قوی: «The user must have double-clicked» — حتماً دوبار کلیک کرده), can't (نمی‌تواند باشد — استنتاجِ منفی: «It can't be the DNS — localhost fails too»). برای حذف: I've ruled out X (X رو حذف کردم), That leaves Y (پس فقط Y می‌مونه), It works until it doesn't (کار می‌کنه تا لحظه‌ای که نمی‌کنه — جملهٔ مقدسِ intermittentها!). و نتیجه: It turned out to be X (معلوم شد X بود).

It can't be the network — localhost fails too. It must be the pool size under load. I've ruled out the query itself; that leaves the connection config. Let me test with a bigger pool.نمی‌تونه شبکه باشه — لوکال هم می‌خوابه. حتماً سایزِ پول زیرِ باره. خودِ کوئری رو حذف کردم؛ پس فقط کانفیگِ اتصال می‌مونه. با پولِ بزرگ‌تر تست می‌کنم.

گفتگو: جفت‌شکارِ سی‌دقیقه‌ای

You: Got 30 minutes to pair? The payments retry is haunted — works in staging, dies in prod. — Colleague: Haunted, my favorite kind. Show me the logs.تو: ۳۰ دقیقه وقت داری پِر شیم؟ retryِ پرداخت جن‌زده‌ست — تو staging کار می‌کنه، تو prod می‌میره. — همکار: جن‌زده، نوعِ موردعلاقه‌ام. لاگ‌ها رو نشونم بده.

Colleague: See this gap? Two retries, same millisecond. — You: Oh. It's a race — both fire before the first one finishes. — Colleague: There it is.همکار: این فاصله رو می‌بینی؟ دو retry، همون میلی‌ثانیه. — تو: او. یه رِیسه — هر دو شلیک می‌شن قبل از اینکه اولی تموم شه. — همکار: پیداش کردیم.

You: I'll add an idempotency key so the second one becomes a no-op. Regression test too. — Colleague: And I'll write the runbook entry — "millisecond retries" — so the next haunted case dies faster.تو: کلیدِ idempotency اضافه می‌کنم که دومی بی‌اثر شه. تستِ رگرسیون هم. — همکار: و من ران‌بوکش رو می‌نویسم — «retryهای میلی‌ثانیه‌ای» — تا جنِ بعدی زودتر بمیره.

اشتباه‌های رایجِ فارسی‌زبان‌ها در همین درس

این بخش را با یک قرارداد بخوان: هر ❌ یعنی «مغزِ فارسی‌زبانت این را می‌سازد و طبیعی است»، و هر ✅ یعنی «این همان چیزی است که گیرندهٔ انگلیسی‌زبان می‌شنود». خطاها اثرِ مستقیمِ ترجمهٔ ذهنیِ فارسی به انگلیسی‌اند؛ با هر جفت بلند تکرار کن تا شکلِ درست در گوشت نشست کند.

❌ This bug is from three days.❌ فارسیِ «سه روزه است» با از/from ترجمه می‌شود؛ مدتْ for است — from نقطهٔ شروع را نشان می‌دهد نه طولِ دوره را. و «سه روزه جان می‌دهد» در انگلیسیِ زنده با حالِ کامل گفته می‌شود: It's been failing.

✅ It's been failing for three days.✅ شکل درست را دو بار بلند بگو؛ حالا یک بار در یک جملهٔ خودت.

❌ The error is happen only when the server is busy.❌ «اتفاق می‌افتد» ذهنِ فارسی را به is + فعلِ خام می‌کشاند؛ happen فعلِ کاملِ ساده است. و قیدِ only چسبیده به فعل می‌نشیند، نه پراکنده در جمله. under load هم همان «بارِ زیاد»ِ تیم‌هاست.

✅ The error only happens when the server is under load.✅ شکل درست را دو بار بلند بگو؛ حالا یک بار در یک جملهٔ خودت.

❌ I tested it, it works in my machine.❌ دو گرهِ معروف در یک جمله: ویرگولِ چسبنده (comma splice) که با خطِ تیره حل می‌شود، و in به‌جای on — «روی ماشینِ من» یعنی on my machine؛ همین جمله ضرب‌المثلِ دنیای دِو است، دست‌کم درستش بگو!

✅ I tested it — it works on my machine.✅ شکل درست را دو بار بلند بگو؛ حالا یک بار در یک جملهٔ خودت.

تمرین‌های این درس — چهار قدم، بی‌عجله

زبانِ شکارِ باگ، زنجیرهٔ حدس و حذف است؛ چهار تمرین را بلند اجرا کن و بعد پاسخ‌ها را باز کن — استنتاجِ نصفه‌گفته، استنتاجِ نصفه‌فروخته است.

زنجیرهٔ استنتاج را کامل کن: «It ___ (can) be the DNS — localhost fails too. It ___ (must) be the connection pool.»
ترجمه کن: «خودِ کوئری را حذف کردم؛ پس فقط کانفیگِ اتصال می‌ماند.» — با قالبِ ruled out / leaves.
حالتِ بی‌ثباتِ معروف را گزارش کن: در staging کار می‌کند، در prod می‌میرد، لوکال هم بازسازی نمی‌شود.
نتیجه را برای تیکت بنویس: «معلوم شد رِیس بین دو retry بود — هر دو قبل از تمام‌شدنِ اولی شلیک شدند» + بگو تستِ regression برایش چه می‌شود — با It turned out.

پاسخ تمرین‌ها — اول خودت جواب بده، بعد باز کن

پاسخ تمرین ۱

can't … must — "It can't be the DNS — localhost fails too. It must be the connection pool." استنتاجِ منفی با can't، استنتاجِ قوی با must؛ جفتِ مقدسِ دیباگ.

پاسخ تمرین ۲

"I've ruled out the query itself — that leaves the connection config." ruled out + that leaves: حذفِ مرحله‌ای، مسیرِ فکرت را برای هم‌تیمی شفاف می‌کند؛ شکارِ باگ رؤیای دیدنی نیست، گزارشِ راه‌رفته است.

پاسخ تمرین ۳

نمونه: "It works in staging but dies in prod — I can't reproduce it locally, even under the same load." کنتراست + بازنشدنیِ صادقانه؛ همین یک قید، نصفِ تیم را به سمتِ درستِ مشکل می‌فرستد.

پاسخ تمرین ۴

"It turned out to be a race between the two retries — both fired before the first one finished. I've added a regression test so it can't sneak back in." پایانِ هر شکار turned out to be است و بیمه‌اش regression test؛ نوشته‌شده در تیکت، دانش می‌ماند.

چالشِ امروز

🎯 باگِ بازِ فعلی‌ات را برای یک همکار در سه جمله روایت کن: نشانه، حذف‌شده‌ها، حدسِ بعدی — و زنجیره را همان‌جا در تیکت کامنت کن.

نکات مکالمهٔ واقعی که کتاب‌ها کم می‌گویند

can't → must → leaves — زنجیرهٔ استنتاج را بلند بگو: «نمی‌تونه X باشه… حتماً Yئه… پس فقط Z می‌مونه» — شنونده، مسیرِ فکرت را می‌خرد نه فقط جواب را.
Can't reproduce را با جزئیات بگو — «Can't reproduce locally — works with 100 users, fails at 10k» — همین یک قید، نصفِ تیم را به سمتِ درستِ مشکل می‌فرستد.
It turned out to be را ثبت کن — پایانِ هر شکار را در تیکت بنویس: «Turned out to be a race between X and Y» — دانشِ پیدا‌شده، فقط وقتی ماندگار است که نوشته شود.

🔑 جمع‌بندی این درس

گزارشِ باگ چهاربندی: انتظار/واقعیت + steps to reproduce + دامنه + زمان. فرضیه‌سازی با قالب: my theory is… / I suspect… / it's either A or B / ruled out. کمک: has anyone seen this? / got 10 minutes to pair? بستنِ حلقه: Found it + regression test. باگِ بی‌ثبات = flaky/intermittent — و توصیفِ دقیق، نصفِ راهِ حل است.

دیباگ به انگلیسی؛ توصیفِ مشکل، فرضیه‌سازی و «found it!»