پرش به محتویات

رفع یک مشکل

BeeWare فهرستی از مسائل شناخته‌شده را ردیابی می‌کند. هر یک از این مسائل می‌تواند موضوع کار قرار گیرد.

این فهرست را می‌توان به روش‌های مختلف فیلتر کرد. برای مثال، می‌توانید بر اساس پلتفرم فیلتر کنید تا روی مشکلاتی که پلتفرم‌های قابل تست شما را تحت تأثیر قرار می‌دهند تمرکز کنید؛ یا می‌توانید بر اساس نوع مشکل، مانند ایرادات مستندسازی، فیلتر کنید. همچنین فیلتری برای مسائل مناسب برای شروع وجود دارد - این‌ها مسائلی هستند که به عنوان مشکلاتی با علت شناخته‌شده شناسایی شده‌اند و ما معتقدیم که رفع آن‌ها باید نسبتاً ساده باشد (اگرچه ممکن است در تحلیل خود اشتباه کنیم).

اگر یک مشکل بیش از شش ماه از ثبت آن گذشته باشد، کاملاً ممکن است که مشکل برطرف شده باشد، بنابراین اولین گام این است که بررسی کنید آیا می‌توانید مشکل را بازتولید کنید. از اطلاعات ارائه‌شده در گزارش باگ برای تلاش در بازتولید مشکل استفاده کنید. اگر نتوانستید مشکل را بازتولید کنید، آنچه یافته‌اید را به‌عنوان نظر در مورد آن مشکل گزارش کنید و یک مشکل دیگر را انتخاب کنید.

اگر می‌توانید مشکل را بازتولید کنید، سعی کنید آن را رفع کنید! بفهمید چه ترکیب از کدها این قابلیت را پیاده‌سازی می‌کند و ببینید چه چیزی به‌درستی کار نمی‌کند.

حتی اگر نتوانید مشکل را حل کنید، گزارش هر چیزی که در طول فرایند کشف می‌کنید به‌عنوان یک نظر در مورد مسئله ارزشمند است. اگر بتوانید منبع مشکل را پیدا کنید اما راه‌حل را نه، آن دانش اغلب برای کسی که با پلتفرم بیشتر آشناست برای حل مسئله کافی خواهد بود. اگر مسئله از قبل یک مورد بازتولید مناسب (یک اپلیکیشن کوچک که کاری جز بازتولید مشکل انجام نمی‌دهد) نداشته باشد، فراهم کردن آن می‌تواند کمک بزرگی باشد.

ارسال یک اصلاحیه

راه‌اندازی محیط توسعه

مشارکت در BeeWare مستلزم راه‌اندازی یک محیط توسعه است.

پیش‌نیازها

شما باید پیش‌نیازهای زیر را نصب کنید.

BeeWare به پایتون 3.10+ نیاز دارد. همچنین به روشی برای مدیریت محیط‌های مجازی (مانند venv) نیاز خواهید داشت.

می‌توانید با اجرای دستور زیر، نسخهٔ پایتونی را که نصب کرده‌اید بررسی کنید:

پایتون ۳.۸.۱۰ (پیش‌فرض، ۲۰ ژوئیه ۲۰۲۰، ۱۶:۱۶:۰۰)

اگر بیش از یک نسخه از پایتون نصب کرده باشید، ممکن است لازم باشد python3 را با شماره نسخهٔ مشخصی جایگزین کنید (مثلاً python3.13)

ما توصیه می‌کنیم از نسخه‌های تازه منتشرشدهٔ پایتون (یعنی نسخه‌هایی که شمارهٔ نسخهٔ خرد «.0» یا «.1» دارند، مانند 3.14.0) خودداری کنید. دلیل آن این است که ابزارهای لازم برای پشتیبانی از پایتون در macOS اغلب با تأخیر عرضه می‌شوند و معمولاً برای نسخه‌های پایدار تازه‌منتشرشدهٔ پایتون در دسترس نیستند.

BeeWare به پایتون 3.10+ نیاز دارد. همچنین به روشی برای مدیریت محیط‌های مجازی (مانند venv) نیاز خواهید داشت.

می‌توانید با اجرای دستور زیر، نسخهٔ پایتونی را که نصب کرده‌اید بررسی کنید:

پایتون ۳.۸.۱۰ (پیش‌فرض، ۲۰ ژوئیه ۲۰۲۰، ۱۶:۱۶:۰۰)

اگر بیش از یک نسخه از پایتون نصب کرده باشید، ممکن است لازم باشد python3 را با شماره نسخهٔ مشخصی جایگزین کنید (مثلاً python3.13)

ما توصیه می‌کنیم از نسخه‌های تازه منتشرشدهٔ پایتون (یعنی نسخه‌هایی که شمارهٔ نسخهٔ خرد «.0» یا «.1» دارند، مانند 3.14.0) خودداری کنید. دلیل آن این است که ابزارهای لازم برای پشتیبانی از پایتون روی لینوکس اغلب با تأخیر عرضه می‌شوند و معمولاً برای نسخه‌های پایدار تازه‌منتشرشدهٔ پایتون در دسترس نیستند.

BeeWare به پایتون 3.10+ نیاز دارد. همچنین به روشی برای مدیریت محیط‌های مجازی (مانند venv) نیاز خواهید داشت.

می‌توانید با اجرای دستور زیر، نسخهٔ پایتونی را که نصب کرده‌اید بررسی کنید:

C:\...>py -3 --version

اگر بیش از یک نسخه از پایتون نصب کرده باشید، ممکن است لازم باشد -3 را با شماره نسخهٔ مشخصی جایگزین کنید (مثلاً -python3.13)

ما توصیه می‌کنیم از نسخه‌های تازه منتشرشدهٔ پایتون (یعنی نسخه‌هایی که شمارهٔ نسخهٔ خرد «.0» یا «.1» دارند، مانند 3.14.0) خودداری کنید. دلیل آن این است که ابزارهای لازم برای پشتیبانی از پایتون روی ویندوز اغلب با تأخیر عرضه می‌شوند و معمولاً برای نسخه‌های پایدار تازه‌منتشرشدهٔ پایتون در دسترس نیستند.

محیط توسعه خود را راه‌اندازی کنید

روش پیشنهادی برای راه‌اندازی محیط توسعهٔ شما برای BeeWare استفاده از یک محیط مجازی است و سپس نصب نسخهٔ توسعهٔ BeeWare و وابستگی‌های آن.

مخزن BeeWare را کلون کنید

سپس به صفحه BeeWare در گیت‌هاب، بروید و اگر قبلاً این کار را نکرده‌اید، مخزن را فورک کنید به حساب کاربری خود. سپس، روی دکمه «<> Code» در فورک خود کلیک کنید. اگر برنامه دسکتاپ گیت‌هاب را روی رایانه خود نصب دارید، می‌توانید «Open with GitHub Desktop» را انتخاب کنید؛ در غیر این صورت، URL HTTPS ارائه‌شده را کپی کرده و از آن برای کلون کردن مخزن روی رایانه خود با استفاده از خط فرمان استفاده کنید:

مخزن BeeWare را فورک کنید، و سپس:

$ git clone https://github.com/<نام کاربری شما>/beeware.git

(نام کاربری گیت‌هاب خود را جایگزین کنید)

مخزن BeeWare را فورک کنید، و سپس:

$ git clone https://github.com/<نام کاربری شما>/beeware.git

(نام کاربری گیت‌هاب خود را جایگزین کنید)

مخزن BeeWare را فورک کنید، و سپس:

C:\...>git clone https://github.com/<نام کاربری شما>/beeware.git

(نام کاربری گیت‌هاب خود را جایگزین کنید)

یک مخزن بالادست تنظیم کنید

پس از فورک کردن، مخزن BeeWare را به‌عنوان یک ریپازیتوری دور upstream اضافه کنید. این کار به کلون محلی شما مرجعی به ریپازیتوری اصلی می‌دهد و همگام‌سازی به‌روزرسانی‌ها را در طول زمان آسان‌تر می‌کند.

همچنین به تگ‌های upstream نیاز دارید تا ابزارهایی مانند Toga و Briefcase بتوانند شماره‌های نسخهٔ دقیق را حل‌کرده و مشخص کنند:

$ git remote add upstream https://github.com/beeware/beeware.git
$ git fetch --tags upstream

$ git remote add upstream https://github.com/beeware/beeware.git
$ git fetch --tags upstream

C:\...>git remote add upstream https://github.com/beeware/beeware.git
C:\...>git fetch --tags upstream

اگر می‌خواهید فورک شما نیز آن تگ‌ها را شامل شود، می‌توانید آن‌ها را پوش کنید:

$ git push --tags

این می‌تواند مفید باشد اگر بعداً یک کلون جدید بسازید و بخواهید تگ‌ها از فورک شما در دسترس باشند.

یک محیط مجازی ایجاد کنید

برای راه‌اندازی یک محیط مجازی و ارتقا pip، اجرا کنید:

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

C:\...>cd beeware
C:\...>py -3 -m venv .venv
C:\...>.venv\Scripts\activate
(.venv) $ python -m pip install -U pip

دستور شما اکنون باید یک پیش‌وند (.venv) در جلوی آن داشته باشد.

نصب کنید

حالا که کد منبع را در اختیار دارید، می‌توانید یک نصب قابل ویرایش از (https://setuptools.pypa.io/en/latest/userguide/development_mode.html) را در محیط توسعه خود انجام دهید. دستور زیر را اجرا کنید:

(.venv) $ python -m pip install -U -e . --group dev

(.venv) $ python -m pip install -U -e . --group dev

(.venv) C:\...>python -m pip install -U -e . --group dev

پیش‌تأیید را فعال کنید

BeeWare از ابزاری به نام pre-commit برای شناسایی مشکلات ساده و استانداردسازی قالب‌بندی کد استفاده می‌کند. این کار با نصب یک گیت هوک انجام می‌شود که پیش از نهایی‌سازی هر commit گیت، به‌طور خودکار مجموعه‌ای از لینترهای کد را اجرا می‌کند. برای فعال‌سازی pre-commit، دستور زیر را اجرا کنید:

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) C:\...>pre-commit install
pre-commit installed at .git/hooks/pre-commit

اکنون شما آماده‌اید تا روی BeeWare هک کردن را شروع کنید!

کار از شعبه

قبل از اینکه روی تغییارتان کار را شروع کنید، مطمئن شوید که یک شاخه ایجاد کرده‌اید. به‌طور پیش‌فرض، وقتی فورک مخزن خود را کلون می‌کنید، روی شاخهٔ main چک‌اوت می‌شوید. این یک کپی مستقیم از شاخهٔ BeeWare در main است.

در حالی که می‌توانید از شاخهٔ main خود درخواست کشش ارسال کنید، ترجیح داده می‌شود این کار را انجام ندهید. اگر درخواستی ارسال کنید که تقریباً درست باشد، عضو تیم اصلی که درخواست شما را بررسی می‌کند ممکن است بتواند تغییرات لازم را اعمال کند، به‌جای اینکه بازخورد دهد و درخواست یک تغییر جزئی کند. با این حال، اگر درخواست کشش خود را از شاخهٔ main ارسال کنید، بازبینان از انجام اصلاحات منع می‌شوند.

کار کردن روی شاخهٔ اصلی شما نیز پس از تکمیل اولین درخواست کشیدن برایتان دشوار می‌شود. اگر بخواهید روی دومین درخواست کشیدن کار کنید، به یک نسخهٔ «تمیز» از شاخهٔ اصلی پروژهٔ بالادست نیاز دارید تا دومین مشارکت خود را بر اساس آن انجام دهید؛ اگر اولین مشارکت خود را از شاخهٔ main انجام داده باشید، دیگر آن نسخهٔ تمیز در دسترس شما نخواهد بود.

در عوض، شما باید تغییرات خود را در یک شعبهٔ ویژگی ایجاد کنید. یک شعبهٔ ویژگی نام ساده‌ای دارد تا تغییری را که ایجاد کرده‌اید شناسایی کند. برای مثال، اگر در حال رفع باگی هستید که باعث مشکلات ساخت (build) در ویندوز ۱۱ می‌شود، ممکن است یک شاخهٔ ویژگی به نام fix-win11-build ایجاد کنید. اگر باگ شما به یک مشکل خاص که گزارش شده است مربوط می‌شود، همچنین رایج است که شمارهٔ آن مشکل را در نام شاخه ذکر کنید (مثلاً fix-1234).

برای ایجاد یک شاخهٔ ویژگی fix-win11-build، اجرا کنید:

(.venv) $ git switch -c fix-win11-build

(.venv) $ git switch -c fix-win11-build

(.venv) C:\...>git switch -c fix-win11-build
مشکل را بازتولید کنید

اگر در وهلهٔ اول مشکلی نداشته باشید، نمی‌توانید آن را رفع کنید. بنابراین، بازتولید مشکل پیش‌نیاز رفع آن است. در نرم‌افزار، به مشکلات معمولاً «باگ» گفته می‌شود و به مسائل اغلب «گزارش باگ» گفته می‌شود.

کسی یک گزارش باگ ارائه کرده است. شما باید تأیید کنید که مراحلی که گزارش‌دهنده شرح داده است، واقعاً منجر به بروز باگ گزارش‌شده می‌شود. آیا می‌توانید با انجام دقیق آنچه در گزارش آمده است، همان نتیجه را بازتولید کنید؟ اگر نمی‌توانید، باید بفهمید چرا.

باگ‌ها در کد

در یک وضعیت ایده‌آل، شما همان پیکربندی را خواهید داشت که فرد گزارش‌دهنده باگ داشته است، مراحل را دنبال می‌کنید و قادر خواهید بود باگ را همان‌طور که توصیف شده بازتولید کنید. با این حال، در بسیاری از موارد، این کار آن‌قدرها هم ساده نخواهد بود. بسیاری از گزارش‌های باگ تنها شامل توضیحات مبهم و مجموعه‌ای مبهم از شرایط هستند. مشکل اینجاست که بسیاری از باگ‌ها بسته به مجموعه‌ای از شرایط دخیل، از جمله نحوه تعامل با آن‌ها، پیش‌نیازهای مختلف، سیستم‌عامل، نسخه سیستم‌عامل، معماری پردازنده، یا اینکه دستگاه کاربر قدیمی و کند است یا جدید و سریع، متفاوت هستند. هرچه اطلاعات بیشتری در مورد شرایط پیرامون باگ داشته باشیم، بهتر است. سعی کنید مجموعه شرایطی را که گزارش‌دهنده ارائه کرده است، بازتولید کنید. اگر نتوانستید این کار را انجام دهید، گام بعدی شما ممکن است درخواست اطلاعات بیشتر از شخصی باشد که باگ را گزارش کرده است.

بهترین روش برای بازتولید یک باگ، استفاده از کوچک‌ترین مثالی است که همچنان مشکل را نشان دهد. در بیشتر موارد، گزارش‌دهندگان مثال حداقلی قابل قبولی ارائه نمی‌دهند؛ اگر هم هر مثالی ارائه کنند، مستقیماً از برنامهٔ «دنیای واقعی» خود کپی می‌کنند. هدف شما این است که گزارش را تا ساده‌ترین شکلی که مشکل را نشان می‌دهد، کاهش دهید. بهترین مورد بازتولید، کوچک‌ترین برنامه ممکن است. این کاهش خود به خود مفید است زیرا مشخص می‌کند که مشکل واقعی چیست. هر کسی می‌تواند مثال حداقلی را اجرا کند و باگی را که توصیف شده است مشاهده خواهد کرد.

اشتباه‌ها در مستندات

باگ‌ها در مستندات می‌توانند به روش‌های مختلفی بروز کنند. مشکلات قالب‌بندی وجود دارد که منجر به مشکلات نمایش می‌شود. گاهی حتی یک باگ هم نیست؛ ممکن است فرد مستندات را اشتباه خوانده باشد یا یک اشتباه واقعی مرتکب شده باشد. این لزوماً به معنای عدم وجود مشکل در مستندات نیست. ممکن است محتوا نامشخص یا مبهم باشد و جای سردرگمی یا سوءتعبیر را باز کند. ممکن است مفهومی که باید مورد بحث قرار گیرد، به دلیل عدم مستندسازی کامل، مطرح نشده باشد.

وقتی برای یک مشکل مستندسازی باگ ثبت می‌شود، باید بررسی کنید که مشکلی که گزارش شده هنوز وجود دارد یا خیر. در مورد مشکلات رندرینگ، باید مستندسازی را کامپایل کنید تا ببینید آیا می‌توانید مشکل را بازتولید کنید یا خیر. مشکلات محتوا صرفاً با خواندن بررسی می‌شوند تا مطمئن شوید هیچ‌کس به‌روزرسانی ارسال نکرده است.

مسئله را به‌روزرسانی کنید

آخرین مرحله در فرایند تریاژ، مستندسازی یافته‌های شما با گذاشتن یک نظر در مورد مشکل است.

اگر می‌توانید مشکل را دقیقاً همان‌طور که توضیح داده شده بازتولید کنید، همین کافی است. یک نظر بگذارید و بگویید که تأیید کرده‌اید دقیقاً همان مشکل را همان‌طور که گزارش‌دهندهٔ اصلی توضیح داده است مشاهده می‌کنید.

اگر می‌توانید هرگونه زمینهٔ اضافی را ارائه دهید، جزئیات آن را درج کنید. این ممکن است شامل توانایی بازتولید مشکل در یک سیستم‌عامل دیگر، یا با نسخهٔ متفاوتی از برخی نرم‌افزارهای درگیر، یا هر چیز دیگری باشد که با گزارش اولیه متفاوت است.

اگر گزارش اصلی جزئیاتی را که برای بازتولید گزارش نیاز داشتید نداشت، آن جزئیات را اضافه کنید. این ممکن است شامل ارائه جزئیات سیستم‌عامل یا نسخه آن، لاگ‌ها یا ردپای استک کامل‌تر، یا دستورالعمل‌های واضح‌تر درباره توالی دقیق عملیات لازم برای بازتولید مشکل باشد. اگر راه ساده‌تری برای بازتولید مشکل پیدا کرده‌اید (یا گزارش‌دهنده اصلی مورد بازتولید را ارائه نکرده)، می‌توانید جزئیات روش بازتولید را نیز درج کنید.

اگر نمی‌توانید مشکل را بازتولید کنید، باز هم یک نظر بگذارید و توضیح دهید چه کارهایی انجام داده‌اید. دانستن اینکه یک مشکل کجا وجود ندارد تقریباً به اندازه دانستن اینکه کجا وجود دارد مهم است، زیرا این به محدود کردن علل احتمالی کمک می‌کند. اگر نظریه‌ای در مورد چرا نمی‌توانید مشکل را بازتولید کنید دارید - برای مثال، اگر فکر می‌کنید این یک خطای کاربری است، یا اینکه مشکل با یک به‌روزرسانی اخیر سیستم‌عامل حل شده است - آن گمانه‌زنی را به عنوان بخشی از نظرتان ذکر کنید.

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

اگر رفع مشکل نیازمند تغییرات در کد باشد:

کد بنویسید، اجرا کنید و تست کنید

رفع یک باگ یا پیاده‌سازی یک قابلیت مستلزم نوشتن مقداری کد جدید است.

ما یک راهنمای سبک کدنویسی داریم که دستورالعمل‌های ما را برای نوشتن کد در BeeWare تشریح می‌کند.

توسعهٔ مبتنی بر آزمون

یک روش خوب برای اطمینان از اینکه کد شما همان کاری را انجام می‌دهد که انتظار دارید، این است که ابتدا یک مورد آزمون برای آن بنویسید. این مورد آزمون در ابتدا باید شکست بخورد، زیرا کدی که قرار است آزمایش شود هنوز موجود نیست. سپس می‌توانید تغییرات لازم در کد را بنویسید تا آزمون با موفقیت اجرا شود و مطمئن شوید که نوشته‌هایتان مسئله‌ای را که انتظار دارید حل می‌کند.

کد خود را اجرا کنید

پس از نوشتن کدتان، باید مطمئن شوید که اجرا می‌شود. برای اطمینان از انجام آنچه انتظار دارید، باید کدتان را به‌صورت دستی اجرا کنید. اگر هنوز این کار را نکرده‌اید، باید یک مورد آزمون برای تغییرات خود بنویسید؛ همان‌طور که در بالا ذکر شد، این آزمون باید در صورتی که کد شما غیرفعال یا موجود نباشد، شکست بخورد.

شما مورد آزمون خود را به مجموعه آزمون‌ها اضافه می‌کنید تا بتوان آن را همراه با سایر آزمون‌ها اجرا کرد. گام بعدی اجرای مجموعه آزمون‌ها است.

اجرای تست‌ها و پوشش

BeeWare از tox برای مدیریت فرایند تست و از pytest برای مجموعه تست‌های خود استفاده می‌کند.

دستور پیش‌فرض tox شامل اجرای موارد زیر است:

  • قلاب‌های پیش از commit
  • towncrier بررسی یادداشت انتشار

  • مستندسازی لینتینگ

  • مجموعه آزمون برای نسخه‌های موجود پایتون

  • گزارش پوشش کد

این اساساً همان چیزی است که CI هنگام ارسال یک درخواست برداشت اجرا می‌کند.

برای اجرای کامل مجموعه تست‌ها، اجرا کنید:

(.venv) $ tox

(.venv) $ tox

(.venv) C:\...>tox

اجرای کل مجموعه تست ممکن است مدتی طول بکشد. شما می‌توانید با اجرای موازی tox، tox p (یا tox run-parallel)، آن را به‌طور قابل توجهی سریع‌تر کنید. وقتی مجموعه تست را به‌صورت موازی اجرا می‌کنید، بازخورد کمتری در مورد پیشرفت آن دریافت خواهید کرد، اما همچنان در پایان اجرای تست، خلاصه‌ای از هر مشکلی که پیدا شده است دریافت می‌کنید. باید خروجی‌ای دریافت کنید که نشان دهد تست‌ها اجرا شده‌اند. ممکن است تست‌های SKIPPED را ببینید، اما هرگز نباید هیچ نتیجه تست FAIL یا ERROR دریافت کنید. ما کل مجموعه تست خود را قبل از ادغام هر پچ اجرا می‌کنیم. اگر این فرآیند به هر مشکلی برخورد کند، آن پچ را ادغام نمی‌کنیم. اگر شما با یک خطا یا شکست تست مواجه شدید، یا در محیط تست شما چیزی عجیب است، یا شما یک مورد حاشیه‌ای (edge case) را پیدا کرده‌اید که ما قبلاً ندیده‌ایم - در هر صورت، به ما اطلاع دهید!

علاوه بر موفقیت آزمون‌ها، این باید ۱۰۰٪ پوشش آزمون را گزارش دهد.

اجرای تست‌های متغیر

تست‌ها را برای نسخه‌های مختلف پایتون اجرا کنید.

به‌طور پیش‌فرض، بسیاری از دستورات tox تلاش می‌کنند مجموعه تست را چندین بار اجرا کنند، یک‌بار برای هر نسخه پایتونی که توسط BeeWare پشتیبانی می‌شود. با این حال، برای انجام این کار، هر یک از نسخه‌های پایتون باید روی سیستم شما نصب شده و در فرآیند کشف پایتون tox در دسترس باشد. به‌طور کلی، اگر نسخه‌ای از پایتون از طریق (https://virtualenv.pypa.io/en/latest/explanation.html#python-discovery) در دسترس باشد، PATH باید بتواند آن را پیدا کرده و از آن استفاده کند.

فقط مجموعه آزمون‌ها را اجرا کنید

اگر در حال تکرار سریع یک ویژگی جدید هستید، نیازی نیست کل مجموعه تست‌ها را اجرا کنید؛ می‌توانید فقط تست‌های واحد را اجرا کنید. برای این کار، اجرا کنید:

(.venv) $ tox -e py

(.venv) $ tox -e py

(.venv) C:\...>tox -e py

اجرای زیرمجموعه‌ای از آزمون‌ها

به‌طور پیش‌فرض، tox تمام تست‌ها را در مجموعه تست واحد اجرا می‌کند. وقتی در حال توسعه تست جدید خود هستید، ممکن است مفید باشد که فقط همان یک تست را اجرا کنید. برای این کار می‌توانید هر مشخص‌کننده pytest را به‌عنوان آرگومان به tox پاس کنید. این مسیرهای تست نسبت به دایرکتوری briefcase هستند. برای مثال، برای اجرای تنها تست‌های یک فایل واحد، اجرا کنید:

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) C:\...>tox -e py -- tests/path_to_test_file/test_some_test.py

شما همچنان هنگام اجرای بخشی از مجموعه آزمون‌ها گزارش پوشش دریافت خواهید کرد، اما نتایج پوشش تنها خطوط کدی را گزارش می‌کنند که توسط آزمون‌های مشخصی که اجرا کرده‌اید، اجرا شده‌اند.

مجموعه تست‌ها را برای یک نسخه مشخص از پایتون اجرا کنید

به‌طور پیش‌فرض tox -e py با هر تفسیرگری که روی سیستم شما با python مطابقت دارد اجرا می‌شود. اگر چندین نسخهٔ پایتون نصب کرده باشید و بخواهید نسخهٔ خاصی را از میان نسخه‌های نصب‌شده آزمایش کنید، می‌توانید نسخهٔ مشخصی را برای استفاده تعیین کنید. برای مثال، برای اجرای مجموعهٔ تست‌ها روی پایتون 3.10، دستور زیر را اجرا کنید:

(.venv) $ tox -e py310

(.venv) $ tox -e py310

(.venv) C:\...>tox -e py310

می‌توان یک زیرمجموعه از تست‌ها را با افزودن -- و یک مشخصهٔ تست به خط فرمان اجرا کرد.

مجموعه تست‌ها را بدون پوشش (سریع) اجرا کنید

به‌طور پیش‌فرض، tox مجموعه تست pytest را در حالت تک‌ریسمانی اجرا می‌کند. می‌توانید با اجرای موازی مجموعه تست، سرعت اجرای آن را افزایش دهید. این حالت به‌دلیل پیچیدگی‌های ثبت پوشش در فرآیندهای spawn شده، فایل‌های پوشش تولید نمی‌کند. برای اجرای یک نسخه از پایتون در حالت «سریع»، دستور زیر را اجرا کنید:

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

(.venv) C:\...>tox -e py-fast

یک زیرمجموعه از تست‌ها را می‌توان با افزودن -- و یک مشخصه تست به خط فرمان اجرا کرد؛ یک نسخهٔ خاص پایتون را می‌توان با افزودن نسخه به هدف تست استفاده کرد (مثلاً py310-fast برای اجرای سریع روی پایتون 3.10).

پوشش کد

BeeWare در پایگاه‌کد خود پوشش ۱۰۰٪ شاخه‌ها را حفظ می‌کند. وقتی در پروژه کد اضافه یا تغییر می‌دهید، باید کد تست اضافه کنید تا پوشش هر تغییری را که ایجاد کرده‌اید تضمین کنید.

با این حال، BeeWare چندین پلتفرم و همچنین چندین نسخه از پایتون را هدف قرار می‌دهد، بنابراین پوشش کامل را نمی‌توان تنها روی یک پلتفرم و نسخه پایتون تأیید کرد. برای رفع این مشکل، چندین قاعده پوشش شرطی در بخش tool.coverage.coverage_conditional_plugin.rules از pyproject.toml تعریف شده‌اند (مثلاً می‌توان از no-cover-if-is-windows برای علامت‌گذاری بخشی از کد استفاده کرد که هنگام اجرای مجموعه تست‌ها روی ویندوز اجرا نخواهد شد). این قواعد برای شناسایی بخش‌های کدی به کار می‌روند که تنها روی پلتفرم‌ها یا نسخه‌های خاصی از پایتون پوشش داده شده‌اند.

شایان ذکر است که گزارش‌گیری پوشش در نسخه‌های مختلف پایتون می‌تواند کمی نامتعارف باشد. برای مثال، اگر فایل‌های پوشش با یک نسخه از پایتون تولید شوند اما گزارش‌گیری پوشش با نسخه‌ای دیگر انجام شود، ممکن است گزارش شامل نتایج مثبت کاذب برای شاخه‌های از دست رفته باشد. به همین دلیل، گزارش‌گیری پوشش همیشه باید با قدیمی‌ترین نسخه‌ای از پایتون که برای تولید فایل‌های پوشش استفاده شده است، انجام شود.

درک نتایج پوشش

در پایان خروجی آزمون پوشش باید گزارشی از داده‌های پوشش جمع‌آوری‌شده وجود داشته باشد:

نام    بیانیه‌ها   مفقود   بخش   پوشش   مفقود
 ---------------------------------------------------
 کل    7540 0   1040 0  100.0%

این به ما می‌گوید که مجموعه آزمون‌ها هر مسیر انشعابی ممکن در کد را اجرا کرده است. این تضمین صددرصدی نیست که هیچ باگی وجود ندارد، اما به این معناست که ما هر خط کد در پایگاه کد را اجرا می‌کنیم.

اگر در پایگاه کد تغییراتی ایجاد کنید، ممکن است در این پوشش یک شکاف ایجاد شود. وقتی این اتفاق می‌افتد، گزارش پوشش به شما می‌گوید کدام خطوط اجرا نمی‌شوند. برای مثال، فرض کنید ما تغییری در some/interesting_file.py ایجاد کردیم و منطق جدیدی اضافه کردیم. گزارش پوشش ممکن است چیزی شبیه به این باشد:

نام   اظهارات    شعبه    بخش    پوشش    مفقود
 -------------------------------------------------------------------------------
 src/some/interesting_file.py 111 1     26 0  98.1%   170, 302-307, 320->335
 -------------------------------------------------------------------------------
 مجموع 7540 1   1726 0  99.9%

این به ما می‌گوید که خط ۱۷۰، خطوط ۳۰۲ تا ۳۰۷ و جهشی از خط ۳۲۰ به خط ۳۳۵ توسط مجموعه آزمون اجرا نمی‌شوند. برای بازیابی این پوشش باید آزمون‌های جدیدی اضافه کنید (یا آزمون موجود را اصلاح کنید).

گزارش پوشش برای پلتفرم میزبان و نسخهٔ پایتون

می‌توانید یک گزارش پوشش برای پلتفرم و نسخهٔ پایتون خود تولید کنید. برای مثال، برای اجرای مجموعهٔ تست‌ها و تولید گزارش پوشش پایتون 3.10، اجرا کنید:

(.venv) $ tox -m test310

(.venv) $ tox -m test310

(.venv) C:\...>tox -m test310

گزارش پوشش برای پلتفرم میزبان

اگر همه نسخه‌های پشتیبانی‌شدهٔ پایتون برای tox در دسترس باشند، می‌توان با اجرای زیر گزارش پوشش برای پلتفرم میزبان را تهیه کرد:

(.venv) $ tox p -m test-platform

(.venv) $ tox p -m test-platform

(.venv) C:\...>tox p -m test-platform

گزارش پوشش در HTML

می‌توان با افزودن -html به هر یک از نام‌های محیط پوشش tox، یک گزارش پوشش HTML تولید کرد، برای مثال:

(.venv) $ tox -e coverage-platform-html

(.venv) $ tox -e coverage-platform-html

(.venv) C:\...>tox -e coverage-platform-html

موضوع فقط نوشتن تست‌ها نیست!

اگرچه ما اطمینان حاصل می‌کنیم که تمام کدهایمان را تست می‌کنیم، اما این وظیفه صرفاً به حفظ آن سطح از تست محدود نمی‌شود. بخشی از این وظیفه، بازبینی کد در حین کار است. می‌توانید مجموعه‌ای جامع از تست‌ها برای یک جلیقه نجات واقعی بنویسید… اما آن جلیقه نجات واقعی همچنان برای هدفی که برای آن طراحی شده بود بی‌فایده خواهد بود!

در حین توسعهٔ تست‌ها، باید بررسی کنید که ماژول اصلی نیز از نظر درونی مطابق باشد. اگر متوجه نام متدهایی شدید که از نظر داخلی سازگار نیستند (مثلاً چیزی در یک ماژول با نام on_select و در ماژول دیگر با نام on_selected)، یا داده‌ها به‌طور یکسان پردازش نمی‌شوند، آن را علامت‌گذاری کرده و با ثبت یک تیکت به ما اطلاع دهید. یا اگر مطمئن هستید که می‌دانید چه کاری باید انجام شود، یک درخواست کش (pull request) ایجاد کنید که مشکل یافته‌شده را برطرف کند.

اگر رفع مشکل مستلزم تغییرات در مستندات باشد:

مستندسازی بسازید

قبل از انجام هرگونه تغییری در مستندات BeeWare، مفید است که تأیید کنید می‌توانید مستندات موجود را بسازید.

شما باید یک تفسیرگر Python 3.13 را نصب و در مسیر خود در دسترس داشته باشید (یعنی python3.13 باید یک تفسیرگر Python 3.13 را راه‌اندازی کند).

BeeWare از tox برای تولید مستندات استفاده می‌کند. دستورات زیر باید از همان محل فایل tox اجرا شوند که در دایرکتوری ریشه پروژه قرار دارد.

پیش‌نمایش مستندات زنده

برای پشتیبانی از ویرایش سریع مستندات، BeeWare دارای حالت «پیش‌نمایش زنده» است.

پیش‌نمایش زنده با هشدارها ساخته خواهد شد!

سرویس زنده برای تکرار و بهبود به‌روزرسانی‌های مستندات شما در دسترس است. در حالی که در حال به‌روزرسانی موارد هستید، ممکن است یک مشکل نشانه‌گذاری ایجاد شود. مشکلاتی که به‌عنوان WARNING در نظر گرفته می‌شوند، باعث شکست ساخت استاندارد می‌شوند، اما سرویس زنده طوری تنظیم شده است که در خروجی کنسول هشدارها را نمایش دهد و در عین حال ساخت را ادامه دهد. این امکان را به شما می‌دهد که بدون نیاز به راه‌اندازی مجدد پیش‌نمایش زنده، فرآیند تکرار را انجام دهید.

یک WARNING با یک ERROR متفاوت است. اگر مسئله‌ای را معرفی کنید که به‌عنوان یک ERROR در نظر گرفته شود، سرویس زنده شکست خواهد خورد و نیاز به راه‌اندازی مجدد دارد. تا زمانی که مسئله WARNING حل نشود، دوباره راه‌اندازی نخواهد شد.

برای راه‌اندازی سرور زنده:

(venv) $ tox -e docs-live

(venv) $ tox -e docs-live

(سمت چپ) C:\...>tox -e docs-live

این کار مستندات را ایجاد می‌کند، یک سرور وب راه‌اندازی می‌کند تا مستندات را ارائه دهد و سیستم فایل را برای هرگونه تغییر در منبع مستندات زیر نظر می‌گیرد.

پس از راه‌اندازی سرور، چیزی شبیه به موارد زیر را در خروجی کنسول مشاهده خواهید کرد:

اطلاعات - [۱۱:۱۸:۵۱] در حال سرویس‌دهی در http://127.0.0.1:8000/

یک مرورگر باز کنید و به آدرس URL ارائه‌شده بروید. اکنون می‌توانید روی مستندات تکرار کنید. اگر تغییری شناسایی شود، مستندات بازسازی خواهد شد و هر مرورگری که صفحهٔ تغییرشده را مشاهده می‌کند، به‌طور خودکار تازه‌سازی خواهد شد.

docs-live یک گام اولیه است.

اجرای docs-live برای کار با سرور زنده جهت تکرارهای اولیه در نظر گرفته شده است. شما باید همیشه قبل از ارسال درخواست کش یک ساخت محلی اجرا کنید.

ساخت محلی

وقتی تکرارها را به پایان رساندید، باید مستندات را به‌صورت محلی بسازید. این فرایند ساخت طوری طراحی شده که در صورت وجود هرگونه مشکل در نشانه‌گذاری با خطا مواجه شود. این کار به شما امکان می‌دهد هر چیزی را که ممکن است در سرور زنده از قلم افتاده باشد، شناسایی کنید.

ایجاد یک بیلد محلی

برای ایجاد یک ساخت محلی:

(venv) $ tox -e docs

(venv) $ tox -e docs

(venv) C:\...>tox -e docs

خروجی این ساخت در دایرکتوری _build در ریشه پروژه قرار خواهد گرفت.

تولید یک بیلد محلی ترجمه‌شده

مستندات BeeWare به چندین زبان ترجمه شده است. به‌روزرسانی‌های مستندات انگلیسی ممکن است در نسخه‌های زبان‌های دیگر مشکل ایجاد کند. مهم است که قبل از ارسال درخواست کش، از کارکرد همه نسخه‌ها اطمینان حاصل کنید.

برای تولید یک نسخه از تمام ترجمه‌های موجود:

(فعل) $ tox -e docs-all

(فعل) $ tox -e docs-all

(venv) C:\...>tox -e docs-all

خروجی هر کامپایل زبان در دایرکتوری مربوطه با نام _build/html/<languagecode> قرار می‌گیرد، که <languagecode> کد دو یا پنج‌نقطه‌ای زبان موردنظر است (مثلاً برای فرانسوی fr، برای ایتالیایی it و غیره).

اگر در یک ساخت مشکل پیدا کنید، می‌توانید آن ساخت را به‌طور جداگانه با اجرای tox -e docs-<languagecode> اجرا کنید. برای مثال، برای ساخت تنها مستندات فرانسوی، اجرا کنید:

(venv) $ tox -e docs-fr

(venv) $ tox -e docs-fr

(venv) C:\...>tox -e docs-fr

خروجی یک ساخت تک‌زبانه در دایرکتوری _build خواهد بود.

لینت‌گذاری مستندات

فرآیند ساخت مشکلات مارک‌داون را شناسایی می‌کند، اما BeeWare بررسی‌های اضافی بیشتری برای سبک و قالب‌بندی انجام می‌دهد که به آن «لینتینگ» گفته می‌شود. برای اجرای بررسی‌های لینت:

(venv) $ tox -e docs-lint

(venv) $ tox -e docs-lint

(venv) C:\...>tox -e docs-lint

این تأیید می‌کند که مستندات حاوی موارد زیر نیست:

  • لینک‌های مرده
  • کلمات اشتباه املایی

اگر املای صحیح یک کلمه به‌عنوان اشتباه شناسایی شود، آن کلمه را در لیست داخل docs/spelling_wordlist اضافه کنید. این کار کلمه را به فرهنگ لغت SpellChecker اضافه می‌کند. هنگام افزودن به این لیست، به خاطر داشته باشید:

  • ما املای آمریکایی را ترجیح می‌دهیم، با برخی آزادی‌ها برای اصطلاحات محاوره‌ای خاص برنامه‌نویسی (مثلاً «apps») و فعل‌انگاری اسامی (مثلاً «scrollable»).
  • هر ارجاع به نام یک محصول باید از شیوهٔ نگارش بزرگ‌نویسی ترجیحی آن محصول استفاده کند. (مثلاً «macOS»، «GTK»، «pytest»، «Pygame»، «PyScript»)
  • اگر یک واژه به‌عنوان «کد» استفاده می‌شود، باید به‌صورت یک عبارت بستی (like this) نقل شود، نه اینکه به فرهنگ لغت اضافه شود.
مستندسازی بنویسید

این‌ها گام‌هایی هستند که باید برای نوشتن مشارکت مستندسازی خود در BeeWare دنبال کنید.

به‌روزرسانی مستندات موجود

اگر در حال ویرایش مستندات موجود هستید، باید فایل را در دایرکتوری /docs/en پیدا کنید. ساختار فایل‌ها مطابق ساختار صفحات است، بنابراین می‌توانید با استفاده از URL مستندات، فایل را بیابید.

افزودن مستندات جدید

اگر در حال افزودن یک سند جدید هستید، چند مرحلهٔ دیگر نیز وجود دارد.

شما باید سند را در مکان مناسب درون دایرکتوری docs/en ایجاد کنید. برای بحث، فرض می‌کنیم شما یک سند جدید با نام فایل new_doc.md اضافه می‌کنید.

سپس باید فایل docs/en/SUMMARY.md را به‌روزرسانی کنید تا فایل جدیدتان را شامل شود. SUMMARY.md اساساً برای بازتاب ساختار دایرکتوری docs/en سازمان‌دهی شده است، اما مهم‌تر از آن، ساختار نوار کناری سمت چپ را به‌طور مستقیم تعیین می‌کند. اگر بخشی را که قصد دارید new_doc.md را در آن درج کنید پیدا کنید و یک مسیر وایلدکارد را مشاهده کنید، نیازی نیست در SUMMARY.md هیچ تغییری ایجاد کنید. برای مثال:

- ./مسیر/به/دایرکتوری/*

اگر بخشی که قصد دارید new_doc.md را در آن قرار دهید شامل فهرستی از لینک‌های جداگانه مارک‌داون باشد، باید یک لینک صریح به لینک خود اضافه کنید. برای مثال:

- [سند جدید من](new_doc.md)

نوشتن مستندات شما

اکنون می‌توانید فایل مورد نظر را در ویرایشگر خود باز کرده و شروع به نوشتن کنید.

ما یک راهنمای سبک مستندسازی داریم که دستورالعمل‌های ما را برای نوشتن مستندسازی BeeWare تشریح می‌کند.

وقتی برای ارسال مشارکت خود آماده‌اید:

اضافه کردن یادداشت تغییر

بسیاری از ابزارهای BeeWare از towncrier برای کمک به ساخت یادداشت‌های انتشار هر نسخه استفاده می‌کنند. وقتی یک درخواست کشش (pull request) را به یکی از ابزارهای مربوطه ارسال می‌کنید، باید شامل یک یادداشت تغییر باشد – این یادداشت تغییر تبدیل به مدخلی در یادداشت‌های انتشار می‌شود که تغییر انجام‌شده را توصیف می‌کند.

هر درخواست کشش باید حداقل یک فایل در دایرکتوری changes/ داشته باشد که توضیح کوتاهی از تغییری که توسط درخواست کشش پیاده‌سازی شده ارائه دهد. یادداشت تغییر باید به فرمت مارک‌داون باشد، در فایلی با نامی به شکل <id>.<fragment type>.md. اگر تغییری که پیشنهاد می‌دهید یک باگ را رفع می‌کند یا ویژگی‌ای را پیاده‌سازی می‌کند که برای آن شماره ایزیس (issue) موجود است، شناسه همان شماره تیکت خواهد بود. اگر تغییر مربوط به هیچ ایرادی نباشد، شماره PR می‌تواند به‌عنوان شناسه استفاده شود. شما تا قبل از ارسال درخواست کشش این شماره را نخواهید دانست، بنابراین اولین مرحله CI در بررسی towncrier شکست خواهد خورد؛ یادداشت تغییر را اضافه کرده و یک به‌روزرسانی PR ارسال کنید تا CI با موفقیت عبور کند.

پنج نوع قطعه وجود دارد:

  • feature: PR یک رفتار یا قابلیت جدید را اضافه می‌کند که قبلاً امکان‌پذیر نبود (مثلاً افزودن پشتیبانی از یک قالب بسته‌بندی جدید، یا یک ویژگی جدید در یک قالب بسته‌بندی موجود)؛
  • bugfix: این PR یک باگ در پیاده‌سازی موجود را رفع می‌کند؛
  • doc: PR یک بهبود قابل توجه در مستندات است؛
  • removal; PR نمایانگر یک تغییر ناسازگار رو به عقب در رابط برنامه‌نویسی کاربردی BeeWare است؛ یا
  • misc; یک تغییر جزئی یا اداری (مثلاً اصلاح یک اشتباه تایپی، یک توضیح زبانی جزئی، یا به‌روزرسانی نسخهٔ یک وابستگی) که نیازی به اعلام در یادداشت‌های انتشار ندارد.

این توضیح در یادداشت تغییر باید یک خلاصه سطح بالا و «بازاریابی» از تغییر از دیدگاه کاربر باشد، نه یک توضیح فنی عمیق یا جزئیات پیاده‌سازی. این با پیام commit متفاوت است – پیام commit شرح می‌دهد چه کاری انجام شده تا توسعه‌دهندگان آینده بتوانند دلیل تغییر را دنبال کنند؛ یادداشت تغییر توصیفی است برای بهره‌مندی کاربران که ممکن است از ساختار داخلی اطلاع نداشته باشند.

برای مثال، اگر شما یک باگ مربوط به نام‌گذاری پروژه را رفع کنید، پیام کامیت ممکن است چنین باشد:

یک بررسی عبارت منظم قوی‌تر اعمال کنید تا نام‌های پروژه‌هایی که با اعداد شروع می‌شوند، مجاز نباشند.

یادداشت تغییر مربوطه چیزی شبیه به این خواهد بود:

نام پروژه‌ها دیگر نمی‌توانند با عدد شروع شوند.

برخی PRها ممکن است چندین ویژگی را معرفی کنند و چندین باگ را رفع نمایند، یا چندین تغییر ناسازگار رو به عقب را اعمال کنند. در این صورت، PR ممکن است چندین فایل یادداشت تغییر داشته باشد. اگر نیاز باشد دو نوع قطعه را با یک شناسه یکسان مرتبط کنید، می‌توانید یک پسوند عددی اضافه کنید. برای مثال، اگر PR 789 ویژگی‌ای را که در تیکت 123 توصیف شده بود اضافه کرده، باگی را که در تیکت 234 توصیف شده بود بسته و همچنین دو تغییر ناسازگار رو به عقب ایجاد کرده باشد، ممکن است 4 فایل یادداشت تغییر داشته باشید:

  • 123.feature.md
  • 234.bugfix.md
  • 789.removal.1.md
  • 789.removal.2.md

برای اطلاعات بیشتر درباره towncrier و انواع فرگمنت‌ها به News Fragments مراجعه کنید. همچنین می‌توانید نمونه‌های موجود فرگمنت‌های خبری را در دایرکتوری changes از مخزن BeeWare مشاهده کنید. اگر این پوشه خالی باشد، احتمالاً به این دلیل است که BeeWare به‌تازگی یک نسخهٔ جدید منتشر کرده است؛ فایل‌های یادداشت تغییرات با هر نسخه حذف و ترکیب می‌شوند تا یادداشت‌های نسخه به‌روزرسانی شوند. می‌توانید آن فایل را ببینید تا با سبک کامنت مورد نیاز آشنا شوید؛ همچنین می‌توانید به PRهای اخیراً ادغام‌شده مراجعه کنید تا نحوه قالب‌بندی یادداشت‌های تغییرات خود را مشاهده کنید.

ارسال درخواست ادغام

حالا که تمام تغییرات‌تان را کامیت کرده‌اید، آماده‌اید تا یک درخواست کش ارسال کنید. برای اینکه فرایند بازبینی به‌خوبی پیش برود، چند مرحله وجود دارد که باید انجام دهید.

کار با پیش‌تعهد

هرگاه شما هر تغییری را commit کنید، pre-commit به‌طور خودکار اجرا می‌شود. اگر در commit مشکلی یافت شود، این امر باعث شکست commit شما خواهد شد. در صورت امکان، pre-commit تغییرات لازم را برای اصلاح مشکلات یافته‌شده اعمال می‌کند. در مثال زیر، یک مشکل در قالب‌بندی کد توسط بررسی ruff یافت شده است:

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) C:\...>git add some/interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

در این مورد، ruff به‌طور خودکار مشکل را برطرف کرد؛ بنابراین می‌توانید هر فایلی را که در نتیجه بررسی‌های پیش از commit تغییر کرده بود دوباره اضافه کرده و تغییر را مجدداً commit کنید. با این حال، برخی بررسی‌ها نیاز به اعمال تغییرات دستی دارند. پس از انجام آن تغییرات، هر فایل تغییر یافته را دوباره اضافه کرده و commit کنید.

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) C:\...>git add some\interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

وقتی همه چیز با موفقیت انجام شود، پیامی خواهید دید که نشان می‌دهد کامیت نهایی شده است و با اجرای git log، کامیت شما به‌عنوان جدیدترین افزوده نمایش داده می‌شود. اکنون آماده‌اید تا تغییرات را به گیت‌هاب پوش کنید.

تغییرات خود را به گیت‌هاب ارسال کنید و درخواست برداشتن (pull request) خود را ایجاد کنید.

اولین باری که به گیت‌هاب ارسال می‌کنید، یک URL به شما ارائه می‌شود که شما را مستقیماً به صفحه گیت‌هاب برای ایجاد یک درخواست کشش جدید هدایت می‌کند. آن URL را دنبال کرده و درخواست کشش خود را ایجاد کنید.

مثال زیر نشان می‌دهد که در push چه انتظاری باید داشت، با URL برجسته شده.

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) C:\...>git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

اگر قبلاً شاخهٔ جاری را به گیت‌هاب ارسال کرده‌اید، دیگر این URL را دریافت نخواهید کرد. با این حال، راه‌های دیگری برای دسترسی به URL ایجاد PR وجود دارد:

  • به مخزن بالادست بروید، روی «درخواست‌های کشیدن» کلیک کنید، سپس «درخواست کشیدن جدید» را انتخاب کرده و شاخه‌ای را که می‌خواهید درخواست خود را از آن ارسال کنید، برگزینید.
  • اگر اخیراً پُش کرده‌اید، به مخزن بالادست بروید، بنری را که بالای فهرست فایل‌ها نشان می‌دهد مخزن «پُش‌های اخیر داشته است» پیدا کنید و روی دکمه «مقایسه و درخواست کشیدن» کلیک کنید.
  • از دستور gh pr create در CLI گیت‌هاب استفاده کنید و پاسخ‌های لازم را وارد کنید.
  • از دستور gh pr create --web در GitHub CLI استفاده کنید تا مرورگر وب به صفحهٔ ایجاد PR باز شود.

هر یک از این گزینه‌ها به شما امکان می‌دهد تا درخواست برداشت جدید خود را ایجاد کنید.

CLI گیت‌هاب: gh

GitHub ابزار GitHub CLI را ارائه می‌دهد که از طریق دستور gh به شما امکان دسترسی به بسیاری از قابلیت‌های GitHub را از طریق ترمینال می‌دهد. مستندات GitHub CLI تمام قابلیت‌ها را پوشش می‌دهد.

محتوای درخواست کشش

عنوان یک درخواست کشش باید آموزنده، واضح و مختصر باشد. در صورت امکان سعی کنید آن را کوتاه نگه دارید، اما در صورت نیاز عناوین طولانی‌تر نیز قابل قبول هستند. یک عنوان خوب برای درخواست کشش باید به فردی بدون هیچ زمینه‌ای، ایده‌ای نسبتاً دقیق از باگ یا ویژگی‌ای که در درخواست شما پیاده‌سازی شده است بدهد.

توضیحات PR باید به‌وضوح تغییرات موجود در PR را منعکس کند. فردی بدون هیچ زمینه‌ای باید بتواند توضیحات شما را بخواند و درک نسبتاً کاملی از دلیل انجام این تغییر به‌دست آورد. از شوخی‌ها، اصطلاحات، زبان محاوره‌ای و قالب‌بندی‌های غیرضروری مانند نوشتن با حروف بزرگ یا استفاده بیش از حد از نشانه‌های نگارشی خودداری کنید؛ هدف ارائه توضیحی ساده و روشن از آنچه در PR شما در حال رخ دادن است، می‌باشد و پرهیز از این موارد توضیحات را برای دیگران قابل‌درک‌تر می‌کند.

اگر هر مورد بازتولید یا هر پروتکل آزمایشی که استفاده کرده‌اید و هنوز جزئی از تغییرات موجود در PR نیست، باید توضیح داده شده و در PR گنجانده شود. توضیح باید شامل نحوه اجرای آن‌ها و اقداماتی باشد که برای بازتولید نتیجه مورد نظر باید انجام داد.

اگر درخواست برداشت شما مشکل شمارهٔ ۱۲۳۴ را حل می‌کند، باید عبارت Fixes #1234 را در توضیحات درخواست برداشت خود درج کنید. این کار باعث می‌شود که وقتی درخواست برداشت ادغام شود، مشکل به‌طور خودکار بسته شود. می‌توانید با استفاده از همان سینتکس #1234 به بحث‌ها، مشکلات یا درخواست‌های برداشت دیگر ارجاع دهید. برای ارجاع به مشکلی در مخزن دیگر، کافی است عدد را با علامت منفی (-) پیش‌وند کنید؛ برای مثال، python/cpython#1234 به مشکل شمارهٔ ۱۲۳۴ در مخزن CPython اشاره می‌کند.

ادغام مستمر

ادغام مداوم، یا CI، فرآیندی است برای اجرای بررسی‌های خودکار روی درخواست برداشت (pull request) شما. این کار می‌تواند شامل بررسی‌های ساده‌ای مانند اطمینان از قالب‌بندی صحیح کد باشد؛ اما شامل اجرای مجموعه تست‌ها و ساخت مستندات نیز می‌شود.

تغییرات متعددی وجود دارد که می‌تواند منجر به شکست CI شود. به‌طور کلی، ما PRهایی را که CI را پاس نمی‌کنند، بررسی نمی‌کنیم. اگر یک pull request بسازید و CI شکست بخورد، تا زمانی که CI پاس نشود، بررسی شما را آغاز نخواهیم کرد. اگر تغییرات شما منجر به شکست شود، مسئولیت شماست که علت را بررسی کرده و مشکل را برطرف کنید.

وقتی CI شکست می‌خورد، لینک‌های شکست در پایین صفحه PR، زیر عنوان «برخی از بررسی‌ها با موفقیت انجام نشدند» نمایش داده می‌شوند. شما فهرستی از چک‌های ناموفق را خواهید دید که در صورت وجود چک‌های موفق نیز در بالای فهرست تمام چک‌ها نمایش داده می‌شود. اگر روی لینک خطا کلیک کنید، به لاگ هدایت می‌شوید. لاگ اغلب تمام اطلاعات لازم برای پی بردن به علت خطا را در اختیار شما قرار می‌دهد. لاگ را مطالعه کنید و سعی کنید بفهمید چرا خطا رخ می‌دهد، سپس برای رفع آن اقدام لازم را انجام دهید.

گاهی اوقات بررسی CI به‌دلیل دلایلی که ارتباطی با تغییرات شما ندارد، ناموفق می‌شود. این ممکن است به‌خاطر مشکلی در ماشینی باشد که بررسی CI را اجرا می‌کند یا به‌دلیل ناپایداری خودِ بررسی CI. اگر با خطا مواجه شدید و مطمئن هستید که ارتباطی با تغییرات شما ندارد، در PR خود توضیحی در این مورد اضافه کنید تا ما بررسی کنیم.

برای راه‌اندازی یک اجرای جدید CI، باید تغییرات جدید را به شاخه‌ی خود پُش کنید.

اگر در موقعیتی قرار گرفتید که برای تأیید CI به کمک نیاز دارید، در PR یک کامنت بگذارید و ما را در جریان بگذارید تا هر چه در توان داریم برای کمک به شما انجام دهیم.

بررسی‌های pre-commit و towncrier

اگر هر یک از بررسی‌های pre-commit یا towncrier با شکست مواجه شود، مانع اجرای بیشتر بررسی‌های CI خواهد شد. قبل از اینکه مجموعه کامل بررسی‌ها اجرا شود، باید مشکلات مربوطه را برطرف کنید.

ما منابع CI محدودی داریم. مهم است بدانید که هر بار که به شاخه push می‌کنید، CI آغاز می‌شود. اگر قصد دارید چندین تغییر انجام دهید، بهتر است آن‌ها را به‌صورت محلی اعمال کرده و همه را یک‌جا push کنید. CI تنها روی جدیدترین commit در هر مجموعه اجرا می‌شود و بدین ترتیب بار سیستم CI ما به حداقل می‌رسد.

فرآیند ارسال PR شما تا زمانی که CI را پاس نکند یا نتوانید توضیح دهید چرا پاس نشده است، کامل نمی‌شود.