استفاده از ابزارها¶
یکی از ارزشمندترین بازخوردهایی که میتوانیم دریافت کنیم، از افرادی است که در تلاش برای استفاده از ابزارهای BeeWare هستند و متوجه میشوند نقطهای از اصطکاک یا ویژگیای مفقود وجود دارد. برای ما فوقالعاده مفید است که هر دشواریای را که ممکن است هنگام استفاده از این ابزارها برای اهداف واقعی تجربه کنید، درک کنیم.
به چیزی فکر کن که همیشه میخواستهای بسازی و سعی کن آن را بسازی. اگر موفق شوی پروژهات را بسازی، تبریک! تو همان چیزی را داری که همیشه میخواستهای.
با این حال، اگر موفق نشدید، به ما بگویید چه چیزی اشتباه پیش رفت. آیا ویژگیای وجود نداشت؟ آیا مستندات گیجکننده است یا در بخشی ناقص است؟ به اشتراک گذاشتن تجربهی شما بینش مفیدی در اختیار ما قرار میدهد که میتوانیم از آن برای شکلدهی به فرایند برنامهریزیمان استفاده کنیم.
اگر با هر مشکلی مواجه شدید، یک موضوع بحث جدید ایجاد کنید، زیرا ممکن است این آغاز یک مشکل جدید یا پیشنهاد یک ویژگی جدید باشد.
مشارکت در استفاده از ابزار¶
ارسال یک مشکل جدید
نوشتن یک گزارش مسئله یا باگ خوب میتواند تفاوت زیادی در توانایی عیبیابی یک مشکل ایجاد کند. در اینجا نحوه ارسال یک گزارش باگ خوب به 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>
پس از اینکه تا حد امکان اطلاعات را ارائه کردید، برای ارسال گزارش روی «ایجاد» کلیک کنید.
پیشنهاد یک ویژگی جدید
پس شما ایدهای برای بهبود BeeWare دارید - چگونه آن را برای بررسی ارسال میکنید؟
تحقیق کنید¶
اولین قدم این است که در ردیاب مشکلات BeeWare به دنبال مشکلات ویژگی (مسائلی که با برچسب «enhancement» مشخص شدهاند)، مشکلات مستندسازی (مسائلی که با برچسب «documentation» مشخص شدهاند) یا موضوعات بحث بگردید تا ببینید آیا این ایده قبلاً پیشنهاد شده است یا خیر. اگر چنین است و شما زمینه یا ایدههای جدیدی برای اضافه کردن دارید، آنها را در همان رشته گفتگو موجود درج کنید. اگر برای تحقیق خود به کمک نیاز دارید، میتوانید در کانال #dev در دیسکورد BeeWare درخواست کمک کنید. ما ممکن است بتوانیم شما را به سمت رشتههای گفتگو موجود راهنمایی کنیم، زمینههایی را که ممکن است از آنها مطلع نباشید ارائه دهیم، یا ایده شما را به ایدهای دیگر که شاید در نگاه اول مرتبط به نظر نرسد، پیوند دهیم.
درباره این ایده بحث کنید¶
اگر هیچ مرجع موجودی برای ایدهتان پیدا نکردید، یک موضوع بحث ایجاد کنید. یک توضیح کلی از هدف و مورد استفاده برای ایدهتان ارائه دهید. هر فکری که در مورد ظاهر این قابلیت در صورت پیادهسازی دارید، مانند شکل کلی یک API، ظاهر بصری یک قابلیت، یا سندی که اضافه خواهد شد، را نیز شامل کنید. در صورت امکان، هر تحقیقی که در مورد نحوه تحقق ایدهتان در پلتفرمهای مختلف انجام دادهاید را نیز باید ضمیمه کنید.
به محض باز شدن رشتهٔ بحث، تیم BeeWare و سایر اعضای جامعه پاسخ خواهند داد. تیم اصلی تلاش خواهد کرد تا ظرف دو روز کاری حداقل یک برداشت اولیه از ایدهٔ شما ارائه دهد. اگر ایدهای بهویژه پیچیده باشد، تحلیل دقیقتر ممکن است تا یک هفته طول بکشد. رویدادهایی مانند تعطیلات و کنفرانسها ممکن است این بازههای زمانی را کمی طولانیتر کنند.
این فرصت شماست تا در گفتوگویی دربارهٔ ایدهتان شرکت کنید. ممکن است از شما بخواهیم جزئیات یا زمینهٔ بیشتری ارائه دهید. سایر اعضای جامعه نیز ممکن است در این بحث مشارکت کنند و دیدگاهها، پیشنهادها یا پیشنهادهای متقابل دیگری ارائه دهند. نتیجهٔ این بحث مراحل بعدی را تعیین خواهد کرد.
مهم است بدانید که همه ایدهها پذیرفته نخواهند شد. دلیل اینکه این فرایند با یک پیشنهاد شروع میشود این است که شما تمام کار را انجام ندهید و بعداً متوجه شوید دلیلی وجود دارد که تغییر شما پذیرفته نمیشود.
این به این معنی نیست که ایدهٔ خوبی نبوده است! ممکن است دلایل فنی وجود داشته باشد که نتوان آن را پیادهسازی کرد. برای مثال، ممکن است ما یک ایده را رد کنیم اگر:
- اجرای قابلاعتماد آن در تمام پلتفرمهای پشتیبانیشده دشوار یا غیرممکن خواهد بود؛ یا
- نگهداری آن دشوار خواهد بود، یا نگهداری مستلزم دسترسی به فناوری یا نرمافزاری است که بهطور گسترده در دسترس نیست؛ یا
- این مخاطب خاصی را هدف قرار میدهد، اما بار زیادی بر سایر کاربران تحمیل میکند.
اگر تشخیص دهیم ایدهی شما مناسب نیست، لزوماً به این معنا نیست که باید از آن دست بکشید. اگرچه ممکن است یک ایدهی مشخص را رد کنیم، اما ممکن است بسیار مایل باشیم رابط افزونه یا نقطهی توسعهی دیگری اضافه کنیم که به شما امکان دهد همان قابلیت را بهعنوان یک کتابخانهی خارجی نگهداری کنید. به این ترتیب میتوانید از آن قابلیت بهرهمند شوید، اما بدون دغدغهها یا محدودیتهای خاص نگهداری، یا بدون اینکه آن قابلیت خود به یک مانع برای پروژه تبدیل شود.
تبدیل به یک درخواست رسمی ویژگی¶
وقتی بحث به اجماع دربارهٔ شکل یک قابلیت رسید، میتوانید در ردیاب مسئلهٔ beeware یک مسئلهٔ درخواست قابلیت جدید ایجاد کنید که خلاصهای از بحث را ارائه دهد و برای زمینه به آن ارجاع دهد.
لازم نیست خودتان پیشنهاد فیچرتان را پیادهسازی کنید؛ میتوانید یک issue با جزئیات آنچه پیشنهاد میدهید باز کنید. با این حال، صرفاً ارسال issue به این معنا نیست که برای شما پیادهسازی خواهد شد. شما باید منتظر بمانید تا ممکن است شخص دیگری که به همان ویژگی علاقهمند است، آن را پیگیری کند، چه عضوی از جامعه باشد یا تیم اصلی؛ اما این امر تضمینشده نیست. اگر میخواهید پیادهسازی تضمینشده باشد، باید خودتان آن را پیادهسازی کنید یا به شخص دیگری برای پیادهسازی آن پول پرداخت کنید.