پیاده‌سازی یک ویژگی جدید¶

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

اگر ویژگی شما نیازمند پیاده‌سازی مخصوص یک پلتفرم باشد، فرایند پیشنهاد باید تأیید کند که ایده می‌تواند روی همه پلتفرم‌ها پیاده‌سازی شود. با این حال، به‌عنوان کسی که برای اولین بار یک ویژگی جدید را پیاده‌سازی می‌کند، شما مسئول پیاده‌سازی آن ویژگی برای همه پلتفرم‌ها نیستید. شما باید پیاده‌سازی کاملی را برای حداقل یک پلتفرم، شامل تست‌ها، ارائه دهید. برای هر پلتفرم دیگر، باید یک پیاده‌سازی «استاب» (stub) ارائه کنید - پیاده‌سازی‌ای که فقط تعریف رابط پایه را فراهم می‌کند، اما یک NotImplementedError را فراخوانی می‌کند یا یک پیام لاگ خروجی می‌دهد تا نشان دهد که آن رفتار روی آن پلتفرم پیاده‌سازی نشده است.

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

افزودن قابلیت جدید¶

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

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

پیش‌نیازها¶

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

macOSLinuxWindows

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 ارائه‌شده را کپی کرده و از آن برای کلون کردن مخزن روی رایانه خود با استفاده از خط فرمان استفاده کنید:

macOSLinuxWindows

مخزن 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 بتوانند شماره‌های نسخهٔ دقیق را حل‌کرده و مشخص کنند:

macOSLinuxWindows

$ 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، اجرا کنید:

macOSLinuxWindows

$ 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) را در محیط توسعه خود انجام دهید. دستور زیر را اجرا کنید:

macOSLinuxWindows

(.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، دستور زیر را اجرا کنید:

macOSLinuxWindows

(.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، اجرا کنید:

macOSLinuxWindows

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

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

(.venv) C:\...>git switch -c fix-win11-build

از گسترش دامنه پروژه جلوگیری کنید

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

گسترش دامنه پروژه برای همه پیش می‌آید. این مفهومی است که برای توسعه‌دهندگان باتجربه کاملاً آشناست؛ همه ما بارها آن را تجربه کرده‌ایم و با تمام مشکلاتی که به همراه دارد روبه‌رو شده‌ایم.

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

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

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

محدود کردن دامنه هر مشارکت به همه افراد درگیر، از جمله خودتان، کمک می‌کند. بازبینان شما و حتی خودتان از آن قدردانی خواهید کرد.

ویژگی جدید را پیاده‌سازی کنید

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

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

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

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

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

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

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

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

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

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

قلاب‌های پیش از commit
towncrier بررسی یادداشت انتشار
مستندسازی لینتینگ
مجموعه آزمون برای نسخه‌های موجود پایتون
گزارش پوشش کد

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

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

macOSLinuxWindows

(.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 باید بتواند آن را پیدا کرده و از آن استفاده کند.

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

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

macOSLinuxWindows

(.venv) $ tox -e py

(.venv) $ tox -e py

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

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

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

macOSLinuxWindows

(.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، دستور زیر را اجرا کنید:

macOSLinuxWindows

(.venv) $ tox -e py310

(.venv) $ tox -e py310

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

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

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

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

macOSLinuxWindows

(.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، اجرا کنید:

macOSLinuxWindows

(.venv) $ tox -m test310

(.venv) $ tox -m test310

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

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

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

macOSLinuxWindows

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

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

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

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

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

macOSLinuxWindows

(.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 حل نشود، دوباره راه‌اندازی نخواهد شد.

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

macOSLinuxWindows

(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 برای کار با سرور زنده جهت تکرارهای اولیه در نظر گرفته شده است. شما باید همیشه قبل از ارسال درخواست کش یک ساخت محلی اجرا کنید.

ساخت محلی¶

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

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

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

macOSLinuxWindows

(venv) $ tox -e docs

(venv) $ tox -e docs

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

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

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

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

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

macOSLinuxWindows

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

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

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

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

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

macOSLinuxWindows

(venv) $ tox -e docs-fr

(venv) $ tox -e docs-fr

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

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

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

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

macOSLinuxWindows

(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 یافت شده است:

macOSLinuxWindows

(.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 کنید.

macOSLinuxWindows

(.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 برجسته شده.

macOSLinuxWindows

(.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 را پاس نکند یا نتوانید توضیح دهید چرا پاس نشده است، کامل نمی‌شود.