پیادهسازی یک ویژگی جدید¶
پس از پایان فرآیند پیشنهاد، باید یک طراحی کامل برای یک ویژگی جدید داشته باشید. این یعنی وقت شروع نوشتن است!
اگر ویژگی شما نیازمند پیادهسازی مخصوص یک پلتفرم باشد، فرایند پیشنهاد باید تأیید
کند که ایده میتواند روی همه پلتفرمها پیادهسازی شود. با این حال، بهعنوان
کسی که برای اولین بار یک ویژگی جدید را پیادهسازی میکند، شما مسئول پیادهسازی
آن ویژگی برای همه پلتفرمها نیستید. شما باید پیادهسازی کاملی را برای حداقل یک
پلتفرم، شامل تستها، ارائه دهید. برای هر پلتفرم دیگر، باید یک پیادهسازی «استاب»
(stub) ارائه کنید - پیادهسازیای که فقط تعریف رابط پایه را فراهم میکند، اما یک
NotImplementedError را فراخوانی میکند یا یک پیام لاگ خروجی میدهد تا نشان دهد
که آن رفتار روی آن پلتفرم پیادهسازی نشده است.
یک بخش مهم از پیادهسازی یک ویژگی جدید، اطمینان از مستندسازی کامل آن است. حداقل این کار مستلزم وجود مستندات API است؛ اما ممکن است نیاز به افزودن راهنمای نحوه انجام یا راهنمای موضوعی نیز باشد.
افزودن قابلیت جدید¶
راهاندازی محیط توسعه
مشارکت در 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
از گسترش دامنه پروژه جلوگیری کنید
«افزایش تدریجی دامنه» زمانی رخ میدهد که فهرست مشکلاتی که با یک مشارکت حل شدهاند یا ویژگیهایی که پیادهسازی شدهاند، بهطور قابلتوجهی فراتر از آنچه در آغاز کار در نظر گرفته شده بود، رشد کند. شما با یک مسئله ساده شروع میکنید؛ یک مشکل مرتبط را کشف میکنید و تصمیم میگیرید آن را هم اصلاح کنید؛ سپس مسئلهای سوم… قبل از آنکه متوجه شوید، یک درخواست کشش دارید که پنج مسئله را بسته و سه ویژگی جدید اضافه کرده و شامل دهها فایل است.
گسترش دامنه پروژه برای همه پیش میآید. این مفهومی است که برای توسعهدهندگان باتجربه کاملاً آشناست؛ همه ما بارها آن را تجربه کردهایم و با تمام مشکلاتی که به همراه دارد روبهرو شدهایم.
دلایل بسیار عملی برای اجتناب از گسترش دامنه وجود دارد. هرچه یک مشارکت بزرگتر شود، کار با آن دشوارتر میشود. شناسایی موارد حاشیهای یا مشکلات احتمالی سختتر میشود، که به این معنی است که کیفیت کلی مشارکت ممکن است کاهش یابد. بازبینیها نیز زمانی که بازبین باید با چندین زمینهٔ بالقوه نامرتبط سروکار داشته باشد، دشوارتر میشوند. یک مشارکت بزرگتر به معنای نظرات بازبینی بیشتر است و برای شما بهعنوان مشارکتکننده، دنبال کردن چندین رشتهٔ بازبینی میتواند دشوار شود. حتی تجربهٔ شما در گیتهاب نیز آسیب میبیند – رابط کاربری گیتهاب با بزرگتر شدن اندازهٔ یک PR کند میشود، به این معنی که پیمایش فایلها از طریق رابط گیتهاب و تلاش برای گذاشتن نظرات بازبینی بهطور فزایندهای دشوار میشود.
هر زمان که دلیلی برای افزودن چیزی به مشارکت خود پیدا کردید که بهطور صریح بخشی از پیشنهاد اصلی یا گزارش باگ نباشد، باید بررسی کنید که آیا در حال مواجهه با گسترش دامنه هستید یا خیر. آیا دو ویژگی متمایز وجود دارد که بتوان آنها را بهطور جداگانه پیادهسازی کرد؟ آیا میتوان یک ویژگی را با یک محدودیت یا باگ شناختهشده پیادهسازی کرد و آن باگ را در یک درخواست کشش بعدی رفع نمود؟ آیا بخشی از رفع باگ از بخش دیگر مستقل است؟ اگر بخشی از یک تغییر را میتوان بدون دستکاری مشارکت اصلی حذف کرد، احتمالاً باید این کار انجام شود.
توسعه نرمافزار همیشه فرآیندی از بهبود تدریجی است. هر مشارکت فردی باید پس از ادغام، پایگاه کد را در وضعیتی بهتر قرار دهد، اما کاملاً قابل قبول است که باگها یا بخشهایی از ویژگیها را بهعنوان کار برای بهبودهای آینده باقی بگذاریم. این ممکن است به معنای تقسیم یک درخواست برداشت (pull request) به چند بخش مستقل برای بازبینی جداگانه باشد، یا ثبت یک مسئله تا شخص دیگری بتواند آن را بررسی و حل کند.
محدود کردن دامنه هر مشارکت به همه افراد درگیر، از جمله خودتان، کمک میکند. بازبینان شما و حتی خودتان از آن قدردانی خواهید کرد.
ویژگی جدید را پیادهسازی کنید
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
towncrierrelease 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.md234.bugfix.md789.removal.1.md789.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 را پاس نکند یا نتوانید توضیح دهید چرا پاس نشده است، کامل نمیشود.