ارسال یک مشکل جدید¶
نوشتن یک گزارش مسئله یا باگ خوب میتواند تفاوت زیادی در توانایی عیبیابی یک مشکل ایجاد کند. در اینجا نحوه ارسال یک گزارش باگ خوب به BeeWare آمده است.
جستجوی مشکلات موجود¶
قبل از ارسال یک مشکل جدید، در فهرست مشکلات موجود جستوجو کنید تا ببینید آیا مشکلی مشابه با مشکل شما وجود دارد یا خیر. اگر یک مشکل باز موجود وجود دارد که به نظر میرسد با مشکل شما مطابقت دارد، با هرگونه اطلاعات اضافی درباره تجربهتان برای آن مشکل یک نظر اضافه کنید. برای مثال، اگر این مشکل را در نسخهٔ دیگری از پایتون یا در سیستمعامل متفاوتی مشاهده میکنید، این اطلاعات اضافی میتواند در تعیین تأثیر یا علت مشکل مفید باشد.
اگر یک مسئلهٔ بسته را پیدا کردید که به نظر میرسد با مشکل شما مطابقت دارد، بررسی کنید که آن مسئله چه زمانی بسته شده است. اگر مسئله بهتازگی بسته شده باشد، احتمالاً باگ شما رفع شده و در انتشار بعدی اصلاح خواهد شد. اگر مسئله بیش از چهار ماه پیش بسته شده باشد، احتمالاً آنچه تجربه میکنید مشکل متفاوتی است – مهم نیست پیام خطا چقدر مشابه به نظر برسد.
اگر مسئلهای را که با آنچه مشاهده میکنید مطابقت دارد پیدا نکردید، ممکن است مناسب باشد که یک مسئله جدید باز کنید.
با یک بحث شروع کنید¶
قبل از ارسال یک مشکل در گیتهاب، در نظر بگیرید که با یک بحث شروع کنید تا بپرسید آیا آنچه تجربه میکنید واقعاً یک باگ است یا مسئلهای در پیکربندی یا فرآیند شما. مگر اینکه رفتاری را مشاهده کنید که مستقیماً با رفتار مستندشده در تضاد باشد، احتمالاً ارزش دارد قبل از ارسال مستقیم گزارش باگ، سؤالی مطرح کنید. اگر مشخص شود که واقعاً یک مشکل پیدا کردهاید، میتوان موضوع بحث را بهراحتی به یک ایتر تبدیل کرد.
شروع یک بحث همچنین میتواند به شما کمک کند تا مطمئن شوید که مشکل را در بهترین مکان گزارش میکنید. اگرچه ممکن است هنگام استفاده از BeeWare با مشکلی مواجه شده باشید، اما این مشکل ممکن است ناشی از یک باگ در پروژهای دیگر در اکوسیستم BeeWare باشد.
نوشتن یک گزارش باگ خوب¶
اگر لازم باشد یک گزارش جدید ثبت شود، مهم است که تا حد امکان جزئیات بیشتری ارائه دهید. یک گزارش باگ خوب شامل تمام اطلاعاتی است که ممکن است به باگ مربوط باشد، و همچنین کوچکترین مثال قابل بازتولید آن.
مثال بازتولیدشده باید تا حد امکان کوتاه و مختصر باشد، در حالی که همچنان مشکل را نشان دهد. ارائهٔ مثالی حجیم عیبیابی را بهطور قابلتوجهی دشوار میکند، بهویژه اگر به کتابخانههای دیگر وابسته باشد یا نیازمند دانش گستردهای از رفتار مورد انتظار یا منطق داخلی مثال باشد.
ما به هرچه جزئیات بیشتری که بتوانید ارائه دهید نیاز داریم. این شامل موارد زیر است، اما قطعاً به آنها محدود نمیشود:
- نسخهٔ سیستمعامل شما - تا ریزنسخه (برای مثال، macOS 15.7.2).
- نسخهٔ پایتون شما، حتی تا نسخهٔ خرد (برای مثال، ۳.۱۴.۱).
- چگونه پایتون را نصب کردید؟ آیا آن را از python.org دانلود کردید؟ آیا از
Homebrew استفاده کردید؟
uv؟pyenv؟conda؟ چیز دیگری؟ - نسخهٔ مشخص ابزارهای BeeWare که استفاده میکنید چیست (برای مثال Toga 0.5.3)؟ اگر از نسخهٔ توسعه استفاده میکنید، از کدام هَش گیت استفاده میکنید؟ گفتن «شعبهٔ اصلی فعلی» کافی نیست، چون ممکن است روزانه تغییر کند.
- نسخههای مشخص بستههای دیگر که باید نصب شوند تا مشکل رخ دهد. میتوانید نتایج
اجرای
python -m pip freezeرا برای ارائه این اطلاعات درج کنید. - اگر یک فایل لاگ تولید شده باشد، کل فایل لاگ.
- اگر یک ردخورد استک تولید شده است، تمام ردخورد استک را ارائه دهید. فقط پیام نهایی خطا را ارائه نکنید – زمینهٔ کامل ردخورد استک مهم است. همچنین بهتر است این را در قالب متن ارائه کنید، نه به صورت اسکرینشات.
- آیا چیز دیگری دربارهٔ راهاندازی رایانه یا شبکهٔ شما وجود دارد که ممکن است بر این مشکل تأثیر بگذارد؟ آیا رایانهٔ شما قدیمی یا کند است؟ آیا این یک رایانهٔ کاری است که ممکن است فایروالها، ویروسکشها یا محدودیتهای دیگری روی آن اعمال شده باشد؟ آیا شبکهٔ شما بهویژه کند است؟ آیا سیستمعامل خود را با تنظیمات پیشفرض غیرمعمول (مانند فونت بسیار بزرگ یا فعالبودن فناوری کمکی دیگری) اجرا میکنید؟
سعی کنید خارج از چارچوب فکر کنید و همه چیزهایی را که ممکن است بر مشکلی که با آن مواجه هستید تأثیر بگذارند، در نظر بگیرید. اگر بیش از آنچه نیاز داریم به ما بدهید، میتوانیم بهراحتی آنچه را که نیاز نداریم نادیده بگیریم. ما نمیتوانیم چیزی را که شما از قلم انداختهاید، پیشنهاد دهیم.
یک مثال حداقلی¶
مهمترین بخش یک گزارش باگ، یک مورد بازتولید حداقلی است. باید امکانپذیر باشد که شخص ثالث دستورالعملهای مورد بازتولید شما را بخواند، آنها را دنبال کند و همان مشکل را مشاهده نماید. این ممکن است به معنای ارائه یک پروژه نمونه باشد که مشکل را نشان میدهد – یا بهتر از آن، استفاده از یک مثال از پیش موجود (مانند یک آموزش یا پروژه نمونهای که بخشی از پایگاه کد موجود است).
کل پروژهٔ شما یک مورد بازتولید حداقلی نیست. یک مورد بازتولید حداقلی نباید شامل هیچ کدی باشد که برای بازتولید مشکل کاملاً ضروری نباشد. در تدوین مورد بازتولید خود بیرحم باشید – اگر دکمهای برای بازتولید مشکل لازم نیست، آن دکمه را اضافه نکنید.
اغلب اوقات، فرایند توسعهٔ این مورد حداقل بازتولید، منبع مشکل را آشکار میکند، زیرا خودِ ساختنِ مثال حداقلی شما را مجبور میکند دقیقاً بفهمید چه چیزی باعث مسئله شده است، چه یک باگ در کد باشد یا ناشی از فرضیات نادرست یا استفادهٔ اشتباه از رابط برنامهنویسی (API).
شما همچنین باید در هر دستورالعمل بازتولید بهطور صریح عمل کنید. گفتن «برنامهٔ نمونه را ببندید» میتواند به معنای کلیک روی دکمهٔ بستن پنجره، انتخاب «خروج» از منو یا فشردن Control-C در ترمینال باشد. گزارش شما نباید هیچ جای ابهامی در مورد اقداماتی که برای بازتولید مشکل باید انجام شود، باقی بگذارد.
ارسال گزارش¶
به فهرست مشکلات پروژه project issues list بروید، روی دکمه «مسئله جدید» کلیک کنید و برای شروع فرایند، «گزارش باگ» را انتخاب کنید.
شما باید تمام بخشها را در قالب مسئله پر کنید. ما این قالب را بهعنوان راهنمایی ارائه میکنیم تا به شما در ارائه اطلاعات لازم کمک کند. به یاد داشته باشید که همیشه میتوانید (و باید!) اطلاعات بیشتری نسبت به آنچه قالب میطلبد ارائه دهید، اما در حداقلترین حالت، ما به تمام اطلاعات موجود در قالب نیاز داریم.
وقتی کد را درج میکنید، در صورتی که بتوانید آن را با یک مثال موجود مانند آموزش BeeWare بازتولید کنید، میتوانید لینک آن را ارائه دهید. در غیر این صورت، کد را در گزارش قرار دهید. کد باید به صورت Markdown قالببندی شود؛ برای یک بلوک کد باید سه بکتیک (```) قبل و بعد از آن قرار دهید.
اگر نیاز دارید یک بلوک طولانی از متن را درج کنید، میتوانید آن را با استفاده از سینتکس زیر به محتوای جمعشده تبدیل کنید:
<details>
<summary>Collapsed content title</summary>
Long block of text.
</details>
پس از اینکه تا حد امکان اطلاعات را ارائه کردید، برای ارسال گزارش روی «ایجاد» کلیک کنید.