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

رفع یک مشکل

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

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

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

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

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

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

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

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

پیش‌نیازها

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

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

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

$ python3 --version

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

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

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

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

$ python3 --version

اگر بیش از یک نسخه از پایتون نصب کرده باشید، ممکن است لازم باشد 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/<your username>/beeware.git

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

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

$ git clone https://github.com/<your username>/beeware.git

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

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

C:\...>git clone https://github.com/<your username>/beeware.git

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

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

برای راه‌اندازی یک محیط مجازی و ارتقا 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
مشکل را بازتولید کنید

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

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

باگ‌ها در کد

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Fixing a bug or implementing a feature will require you to write some new code.

We have a code style guide that outlines our guidelines for writing code for BeeWare.

Test-driven development

A good way to ensure your code is going to do what you expect it to, is to first write a test case to test for it. This test case should fail initially, as the code it is testing for is not yet present. You can then write the code changes needed to make the test pass, and know that what you've written is solving the problem you are expecting it to.

Run your code

Once your code is written, you need to ensure it runs. You'll need to manually run your code to verify it is doing what you expect. If you haven't already, you'll want to write a test case for your changes; as mentioned above, this test should fail if your code is commented out or not present.

You'll add your test case to the test suite, so it can be run alongside the other tests. The next step is to run the test suite.

Running tests and coverage

BeeWare uses tox to manage the testing process and pytest for its own test suite.

The default tox command includes running:

  • pre-commit hooks
  • towncrier release note check

  • documentation linting

  • test suite for available Python versions

  • code coverage reporting

This is essentially what is run by CI when you submit a pull request.

To run the full test suite, run:

(.venv) $ tox

(.venv) $ tox

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

The full test suite can take a while to run. You can speed it up considerably by running tox in parallel, by running tox p (or tox run-parallel). When you run the test suite in parallel, you'll get less feedback on the progress of the test suite as it runs, but you'll still get a summary of any problems found at the end of the test run. You should get some output indicating that tests have been run. You may see SKIPPED tests, but shouldn't ever get any FAIL or ERROR test results. We run our full test suite before merging every patch. If that process discovers any problems, we don't merge the patch. If you do find a test error or failure, either there's something odd in your test environment, or you've found an edge case that we haven't seen before - either way, let us know!

In addition to the tests passing, this should report 100% test coverage.

Running test variations

Run tests for multiple versions of Python

By default, many of the tox commands will attempt to run the test suite multiple times, once for each Python version supported by BeeWare. To do this, though, each of the Python versions must be installed on your machine and available to tox's Python discovery process. In general, if a version of Python is available via PATH, then tox should be able to find and use it.

Run only the test suite

If you're rapidly iterating on a new feature, you don't need to run the full test suite; you can run only the unit tests. To do this, run:

(.venv) $ tox -e py

(.venv) $ tox -e py

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

Run a subset of tests

By default, tox will run all tests in the unit test suite. When you're developing your new test, it may be helpful to run just that one test. To do this, you can pass in any pytest specifier as an argument to tox. These test paths are relative to the briefcase directory. For example, to run only the tests in a single file, run:

(.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

You'll still get a coverage report when running a part of the test suite - but the coverage results will only report the lines of code that were executed by the specific tests you ran.

Run the test suite for a specific Python version

By default tox -e py will run using whatever interpreter resolves as python on your machine. If you have multiple Python versions installed, and want to test a specific Python version from the versions you have installed, you can specify a specific Python version to use. For example, to run the test suite on Python 3.10, run:

(.venv) $ tox -e py310

(.venv) $ tox -e py310

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

A subset of tests can be run by adding -- and a test specification to the command line.

Run the test suite without coverage (fast)

By default, tox will run the pytest suite in single threaded mode. You can speed up the execution of the test suite by running the test suite in parallel. This mode does not produce coverage files due to complexities in capturing coverage within spawned processes. To run a single python version in "fast" mode, run:

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

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

A subset of tests can be run by adding -- and a test specification to the command line; a specific Python version can be used by adding the version to the test target (e.g., py310-fast to run fast on Python 3.10).

Code coverage

BeeWare maintains 100% branch coverage in its codebase. When you add or modify code in the project, you must add test code to ensure coverage of any changes you make.

However, BeeWare targets multiple platforms, as well as multiple versions of Python, so full coverage cannot be verified on a single platform and Python version. To accommodate this, several conditional coverage rules are defined in the tool.coverage.coverage_conditional_plugin.rules section of pyproject.toml (e.g., no-cover-if-is-windows can be used to flag a block of code that won't be executed when running the test suite on Windows). These rules are used to identify sections of code that are only covered on particular platforms or Python versions.

Of note, coverage reporting across Python versions can be a bit quirky. For instance, if coverage files are produced using one version of Python but coverage reporting is done on another, the report may include false positives for missed branches. Because of this, coverage reporting should always use the oldest version Python used to produce the coverage files.

Understanding coverage results

At the end of the coverage test output there should be a report of the coverage data that was gathered:

Name    Stmts   Miss Branch BrPart   Cover   Missing
----------------------------------------------------
مجموع ۷٬۵۴۰ ۰ ۱٬۰۴۰ ۰ ۱۰۰٫۰٪

This tells us that the test suite has executed every possible branching path in the code. This isn't a 100% guarantee that there are no bugs, but it does mean that we're exercising every line of code in the codebase.

If you make changes to the codebase, it's possible you'll introduce a gap in this coverage. When this happens, the coverage report will tell you which lines aren't being executed. For example, lets say we made a change to some/interesting_file.py, adding some new logic. The coverage report might look something like:

نام‌ها، بیانیه‌ها، خانم، شاخه، بخش، پوشش مفقود است
--------------------------------------------------------------------------------
src/some/interesting_file.py 111 1 26 0 98.1% 170, 302-307, 320->335
--------------------------------------------------------------------------------
مجموع ۷٬۵۴۰ ۱٬۱۷۲۶ ۰ ۹۹٫۹٪

This tells us that line 170, lines 302-307, and a branch jumping from line 320 to line 335, are not being executed by the test suite. You'll need to add new tests (or modify an existing test) to restore this coverage.

Coverage report for host platform and Python version

You can generate a coverage report for your platform and version of Python. For example, to run the test suite and generate a coverage report on Python 3.10, run:

(.venv) $ tox -m test310

(.venv) $ tox -m test310

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

Coverage report for host platform

If all supported versions of Python are available to tox, then coverage for the host platform can be reported by running:

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

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

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

Coverage reporting in HTML

A HTML coverage report can be generated by appending -html to any of the coverage tox environment names, for instance:

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

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

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

It's not just about writing tests!

Although we ensure that we test all of our code, the task isn't just about maintaining that level of testing. Part of the task is to audit the code as you go. You could write a comprehensive set of tests for a concrete life jacket… but a concrete life jacket would still be useless for the purpose it was intended!

As you develop tests, you should be checking that the core module is internally consistent as well. If you notice any method names that aren't internally consistent (e.g., something called on_select in one module, but called on_selected in another), or where the data isn't being handled consistently, flag it and bring it to our attention by raising a ticket. Or, if you're confident that you know what needs to be done, create a pull request that fixes the problem you've found.

///

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

/// details-abstract | مستندسازی بسازید

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



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

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

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

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

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

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

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

///

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



/// tab | macOS



```console
(venv) $ tox -e docs-live

(venv) $ tox -e docs-live

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

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

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

INFO    -  [11:18:51] Serving on 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 به چندین زبان ترجمه شده است. به‌روزرسانی‌های مستندات انگلیسی ممکن است در نسخه‌های زبان‌های دیگر مشکل ایجاد کند. مهم است که قبل از ارسال درخواست کش، از کارکرد همه نسخه‌ها اطمینان حاصل کنید.

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

(venv) $ tox -e docs-all

(venv) $ 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 هیچ تغییری ایجاد کنید. برای مثال:

- ./path/to/directory/*

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

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