انتقل إلى المحتوى

تنفيذ ميزة جديدة

بمجرد انتهاء عملية الاقتراح، يجب أن يكون لديك تصميم كامل للميزة الجديدة. وهذا يعني أن الوقت قد حان لبدء الكتابة!

إذا كانت الميزة الخاصة بك تتطلب تنفيذًا خاصًا بمنصة معينة، فيجب أن تكون عملية الاقتراح قد أثبتت أن الفكرة يمكن تنفيذها على جميع المنصات. ومع ذلك، بصفتك الشخص الذي ينفذ ميزة جديدة لأول مرة، فأنت لست مسؤولاً عن تنفيذ الميزة الجديدة لجميع المنصات. تحتاج إلى توفير تنفيذ كامل لـ على الأقل منصة واحدة، بما في ذلك الاختبارات. بالنسبة لأي منصات أخرى، ستحتاج إلى توفير تنفيذ "مبدئي" - وهو تنفيذ يوفر تعريف الواجهة الأساسي، ولكنه يثير خطأ NotImplementedError أو ينتج رسالة سجل تفيد بأن السلوك لم يتم تنفيذه على تلك المنصة.

جزء مهم من تنفيذ ميزة جديدة هو التأكد من أن الميزة موثقة بالكامل. وهذا يعني على الأقل التأكد من وجود وثائق API؛ ولكن قد يتطلب ذلك أيضًا إضافة دليل إرشادي أو دليل موضوعي.

المساهمة بوظائف جديدة

إعداد بيئة التطوير

للمساهمة في BeeWare، يتعين عليك إعداد بيئة تطوير.

المتطلبات الأساسية

ستحتاج إلى تثبيت المتطلبات الأساسية التالية.

BeeWare يتطلب Python 3.10+. ستحتاج أيضًا إلى طريقة لإدارة البيئات الافتراضية (مثل venv).

يمكنك التحقق من إصدار Python الذي قمت بتثبيته عن طريق تشغيل:

$ python3 --version

إذا كان لديك أكثر من إصدار واحد من Python مثبتًا، فقد تحتاج إلى استبدال python3 برقم إصدار محدد (على سبيل المثال، python3.13)

نوصي بتجنب الإصدارات الحديثة من Python (أي الإصدارات التي تحتوي على رقم إصدار فرعي ".0" أو ".1"، مثل 3.14.0). وذلك لأن الأدوات اللازمة لدعم Python على macOS غالبًا ما تكون متأخرة ولا تتوفر للإصدارات المستقرة الحديثة من Python.

BeeWare يتطلب Python 3.10+. ستحتاج أيضًا إلى طريقة لإدارة البيئات الافتراضية (مثل venv).

يمكنك التحقق من إصدار Python الذي قمت بتثبيته عن طريق تشغيل:

$ python3 --version

إذا كان لديك أكثر من إصدار واحد من Python مثبتًا، فقد تحتاج إلى استبدال python3 برقم إصدار محدد (على سبيل المثال، python3.13)

نوصي بتجنب الإصدارات الحديثة من Python (أي الإصدارات التي تحتوي على رقم إصدار فرعي ".0" أو ".1"، مثل 3.14.0). وذلك لأن الأدوات اللازمة لدعم Python على Linux غالبًا ما تكون متأخرة ولا تتوفر للإصدارات المستقرة الحديثة من Python.

BeeWare يتطلب Python 3.10+. ستحتاج أيضًا إلى طريقة لإدارة البيئات الافتراضية (مثل venv).

يمكنك التحقق من إصدار Python الذي قمت بتثبيته عن طريق تشغيل:

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

إذا كان لديك أكثر من إصدار واحد من Python مثبتًا، فقد تحتاج إلى استبدال -3 برقم إصدار محدد (على سبيل المثال، -python3.13)

نوصي بتجنب الإصدارات الحديثة من Python (أي الإصدارات التي تحتوي على رقم إصدار فرعي ".0" أو ".1"، مثل 3.14.0). وذلك لأن الأدوات اللازمة لدعم Python على Windows غالبًا ما تكون متأخرة ولا تتوفر للإصدارات المستقرة الحديثة من Python.

قم بإعداد بيئة التطوير الخاصة بك

الطريقة الموصى بها لإعداد بيئة التطوير لـ BeeWare هي استخدام بيئة افتراضية, ثم تثبيت إصدار التطوير لـ BeeWare وتبعياته.

نسخ مستودع BeeWare

بعد ذلك، انتقل إلى صفحة BeeWare على GitHub، وإذا لم تكن قد قمت بذلك بالفعل، فقم بفصل المستودع إلى حسابك الخاص. بعد ذلك، انقر على زر "<> Code" في النسخة المنقسمة. إذا كان تطبيق GitHub desktop مثبتًا على جهاز الكمبيوتر الخاص بك، فيمكنك تحديد "Open with GitHub Desktop"؛ وإلا، فانسخ عنوان URL HTTPS المقدم، واستخدمه لنسخ المستودع إلى جهاز الكمبيوتر الخاص بك باستخدام سطر الأوامر:

قم بتقسيم مستودع BeeWare، ثم:

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

(استبدل اسم المستخدم الخاص بك على GitHub)

قم بتقسيم مستودع BeeWare، ثم:

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

(استبدل اسم المستخدم الخاص بك على GitHub)

قم بتقسيم مستودع BeeWare، ثم:

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

(استبدل اسم المستخدم الخاص بك على GitHub)

إنشاء بيئة افتراضية

لإعداد بيئة افتراضية وترقية 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).

تثبيت BeeWare

الآن بعد أن أصبح لديك شفرة المصدر، يمكنك إجراء تثبيت قابل للتحرير لـ BeeWare في بيئة التطوير الخاصة بك. قم بتشغيل الأمر التالي:

(.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 لتحديد المشكلات البسيطة وتوحيد تنسيق الكود. ويقوم بذلك عن طريق تثبيت git hook الذي يقوم تلقائيًا بتشغيل سلسلة من أدوات فحص الكود قبل إنهاء أي git 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!

العمل من فرع

قبل البدء في العمل على التغيير، تأكد من إنشاء فرع. بشكل افتراضي، عند استنساخ مستودعك الفرعي، سيتم تسجيل خروجك من الفرع الرئيسي. هذا نسخة مباشرة من الفرع الرئيسي لـ BeeWare.

على الرغم من أنه يمكنك إرسال طلب سحب من فرعك الرئيسي، إلا أنه من الأفضل عدم القيام بذلك. إذا أرسلت طلب سحب شبه صحيح، فقد يتمكن عضو الفريق الأساسي الذي يراجع طلب السحب الخاص بك من إجراء التغييرات اللازمة، بدلاً من تقديم ملاحظات تطلب إجراء تغيير بسيط. ومع ذلك، إذا أرسلت طلب السحب من فرعك الرئيسي، فلن يتمكن المراجعون من إجراء تعديلات.

العمل على الفرع الرئيسي يجعل الأمر صعبًا عليك أيضًا بعد إكمال طلب السحب الأول. إذا كنت ترغب في العمل على طلب سحب ثانٍ، فستحتاج إلى نسخة "نظيفة" من الفرع الرئيسي للمشروع الأصلي لتستند إليها في مساهمتك الثانية؛ إذا كنت قد قدمت مساهمتك الأولى من الفرع الرئيسي، فلن تكون تلك النسخة النظيفة متاحة لك بعد الآن.

بدلاً من ذلك، يجب إجراء التغييرات على فرع الميزة. يتميز فرع الميزة باسم بسيط لتعريف التغيير الذي قمت بإجرائه. على سبيل المثال، إذا كنت تقوم بإصلاح خطأ يسبب مشكلات في البناء على Windows 11، فيمكنك إنشاء فرع ميزة 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
تجنب توسع نطاق العمل

يحدث "توسع النطاق" عندما تنمو قائمة المشكلات التي تم حلها أو الميزات التي تم تنفيذها من خلال مساهمة واحدة بشكل كبير بما يتجاوز ما كان مقرراً عند بدء العمل. تبدأ بمشكلة بسيطة؛ ثم تكتشف مشكلة وثيقة الصلة بها، وتقرر تضمين هذا الإصلاح أيضاً؛ ثم مشكلة ثالثة… وقبل أن تدرك ذلك، يكون لديك طلب سحب يغلق 5 مشكلات ويضيف 3 ميزات جديدة، بما في ذلك عشرات الملفات.

تحدث تجاوزات النطاق للجميع. إنه مفهوم مألوف جدًا للمطورين المتمرسين؛ فقد مررنا جميعًا به عدة مرات، وواجهنا جميع المشكلات التي ترافقه.

هناك أسباب عملية جدًا لتجنب توسع نطاق العمل. فكلما زادت المساهمة، زادت صعوبة العمل عليها. يصبح من الصعب تحديد الحالات الاستثنائية أو المشاكل المحتملة، مما يعني أن الجودة الإجمالية للمساهمة قد تنخفض. تصبح المراجعات أيضًا أكثر صعوبة عندما يحتاج المراجع إلى التعامل مع سياقات متعددة قد لا تكون ذات صلة. تعني المساهمة الأكبر عددًا أكبر من تعليقات المراجعة، وبصفتك مساهمًا، قد يصبح من الصعب متابعة سلاسل المراجعة المتعددة. حتى تجربتك على GitHub ستتأثر - ستتباطأ واجهة مستخدم GitHub مع زيادة حجم PR، مما يعني أن التنقل بين الملفات عبر واجهة GitHub ومحاولة ترك تعليقات المراجعة سيصبح أكثر صعوبة.

في أي وقت تجد سببًا لإضافة أي شيء إلى مساهمتك لا يشكل جزءًا صريحًا من الاقتراح الأصلي أو تقرير الخطأ، يجب أن تفكر فيما إذا كنت تتجه نحو تجاوز النطاق. هل هناك ميزتان متميزتان يمكن تنفيذهما بشكل منفصل؟ هل يمكن تنفيذ ميزة مع وجود قيود أو خطأ معروف، وإصلاح هذا الخطأ في طلب سحب متابعة؟ هل جزء من إصلاح الخطأ مستقل عن الجزء الآخر؟ إذا كان من الممكن استبعاد جزء من التغيير دون تغيير المساهمة الأصلية، فمن الأفضل القيام بذلك.

تطوير البرمجيات هو دائمًا عملية تحسين تدريجي. يجب أن تؤدي كل مساهمة فردية إلى تحسين قاعدة الكود نتيجة دمجها، ولكن من المقبول تمامًا ترك الأخطاء أو أجزاء من الميزات كعمل للتحسين في المستقبل. قد يعني ذلك تقسيم طلب السحب إلى أجزاء متعددة يمكن مراجعتها بشكل مستقل، أو تسجيل مشكلة حتى يتمكن شخص آخر من التحقيق فيها وحلها.

تحديد نطاق كل مساهمة يساعد جميع المعنيين، بمن فيهم أنت. سيقدر ذلك المراجعون، وحتى أنت.

تنفيذ الميزة الجديدة

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
----------------------------------------------------
المجموع 7540 0 1040 0 100.0%

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:

الاسم Stmts الآنسة برانش BrPart غلاف مفقود
--------------------------------------------------------------------------------
src/some/interesting_file.py 111 1 26 0 98.1% 170، 302-307، 320->335
--------------------------------------------------------------------------------
المجموع 7540 1 1726 0 99.9%

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` التالية من
نفس موقع ملف `tox.ini`، الموجود في الدليل الجذر للمشروع.

### معاينة التوثيق المباشر

لدعم التحرير السريع للوثائق، يحتوي BeeWare على وضع "المعاينة
المباشرة".

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

توثيق linting

ستحدد عملية البناء مشاكل Markdown، ولكن BeeWare تقوم ببعض الفحوصات الإضافية للنمط والتنسيق، والمعروفة باسم "linting". لتشغيل فحوصات lint:

(venv) $ tox -e docs-lint

(venv) $ tox -e docs-lint

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

سيؤكد ذلك أن الوثائق لا تحتوي على:

  • روابط معطلة
  • الكلمات المكتوبة بشكل خاطئ

إذا تم تحديد تهجئة صحيحة لكلمة ما على أنها خاطئة، فقم بإضافة الكلمة إلى القائمة الموجودة في docs/spelling_wordlist. سيؤدي ذلك إلى إضافة الكلمة إلى قاموس المدقق الإملائي. عند الإضافة إلى هذه القائمة، تذكر ما يلي:

  • نفضل استخدام قواعد الإملاء الأمريكية، مع بعض الحرية في استخدام المصطلحات العامية الخاصة بالبرمجة (مثل "apps") وتحويل الأسماء إلى أفعال (مثل "scrollable").
  • يجب أن تستخدم أي إشارة إلى اسم منتج الأحرف الكبيرة المفضلة للمنتج. (على سبيل المثال، "macOS" و"GTK" و"pytest" و"Pygame" و"PyScript").
  • إذا كان المصطلح يستخدم "ككود"، فيجب اقتباسه حرفياً (مثل هذا) بدلاً من إضافته إلى القاموس.

///

كتابة الوثائق

هذه هي الخطوات التي يجب اتباعها لكتابة مساهمتك في الوثائق لـ 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 فيه عبارة عن قائمة من روابط Markdown الفردية، فستحتاج إلى إضافة رابط صريح إلى رابطك. على سبيل المثال:

- [My new document](new_doc.md)

كتابة الوثائق الخاصة بك

يمكنك الآن فتح الملف المطلوب في محررك وبدء الكتابة.

لدينا دليل أسلوب التوثيق الذي يحدد إرشاداتنا لكتابة وثائق BeeWare.

إضافة ملاحظة تغيير

تستخدم العديد من أدوات BeeWare towncrier للمساعدة في إنشاء ملاحظات الإصدار لكل إصدار. عند إرسال طلب سحب إلى إحدى الأدوات المطبقة، يجب أن يتضمن ملاحظة تغيير - ستصبح ملاحظة التغيير هذه مدخلاً في ملاحظات الإصدار تصف التغيير الذي تم إجراؤه.

يجب أن يتضمن كل طلب سحب ملفًا واحدًا على الأقل في دليل changes/ يوفر وصفًا موجزًا للتغيير الذي تم تنفيذه بواسطة طلب السحب. يجب أن تكون ملاحظة التغيير بتنسيق Markdown، في ملف يحمل اسم التنسيق <id>.<fragment type>.md. إذا كان التغيير الذي تقترحه سيصلح خطأً أو ينفذ ميزة لها رقم مشكلة موجود، فسيكون المعرف هو رقم تلك التذكرة. إذا لم يكن للتغيير مشكلة مقابلة، فيمكن استخدام رقم PR كرقم تعريف. لن تعرف رقم PR هذا حتى تقوم بدفع طلب السحب، لذا ستفشل أول عملية CI في فحص towncrier؛ أضف ملاحظة التغيير وقم بدفع تحديث PR وستنجح عملية CI.

هناك خمسة أنواع من الأجزاء:

  • الميزة: يضيف PR سلوكًا أو إمكانية جديدة لم تكن ممكنة من قبل (على سبيل المثال، إضافة دعم لتنسيق تغليف جديد، أو ميزة جديدة في تنسيق تغليف موجود بالفعل)؛
  • bugfix: يعمل PR على إصلاح خطأ في التنفيذ الحالي؛
  • doc: تمثل العلاقات العامة تحسناً كبيراً في التوثيق؛
  • إزالة؛ يمثل PR تغييرًا غير متوافق مع الإصدارات السابقة في BeeWare API؛ أو
  • misc؛ تغيير بسيط أو إداري (مثل تصحيح خطأ مطبعي أو توضيح لغوي بسيط أو تحديث إصدار تابع) لا يحتاج إلى الإعلان عنه في ملاحظات الإصدار.

يجب أن يكون هذا الوصف في ملاحظة التغيير ملخصًا "تسويقيًا" عالي المستوى للتغيير من منظور المستخدم، وليس وصفًا تقنيًا عميقًا أو تفاصيل التنفيذ. وهو يختلف عن رسالة الالتزام - حيث تصف رسالة الالتزام ما تم القيام به حتى يتمكن المطورون في المستقبل من متابعة أسباب التغيير؛ أما ملاحظة التغيير فهي وصف لصالح المستخدمين، الذين قد لا يكون لديهم معرفة بالجوانب الداخلية.

على سبيل المثال، إذا قمت بإصلاح خطأ متعلق بتسمية المشروع، فقد يكون نص رسالة الالتزام كما يلي:

تطبيق فحص تعبير عادي أقوى لمنع أسماء المشاريع التي تبدأ بأرقام.

ستكون ملاحظة التغيير المقابلة كما يلي:

لم يعد من الممكن أن تبدأ أسماء المشاريع بأرقام.

بعض طلبات السحب (PR) ستقدم ميزات متعددة وتصلح أخطاء متعددة، أو تقدم تغييرات متعددة غير متوافقة مع الإصدارات السابقة. في هذه الحالة، قد يحتوي PR على عدة ملفات ملاحظات تغيير. إذا كنت بحاجة إلى ربط نوعين من الأجزاء بنفس المعرف، يمكنك إضافة لاحقة رقمية. على سبيل المثال، إذا أضاف PR 789 ميزة موصوفة في التذكرة 123، وأغلق خطأ موصوف في التذكرة 234، وأجرى أيضًا تغييرين غير متوافقين مع الإصدارات السابقة، فقد يكون لديك 4 ملفات ملاحظات تغيير:

  • 123.feature.md
  • 234.تصحيح الأخطاء.md
  • 789.removal.1.md
  • 789.removal.2.md

لمزيد من المعلومات حول towncrier وأنواع الأجزاء، انظر أجزاء الأخبار. يمكنك أيضًا الاطلاع على أمثلة موجودة لأجزاء الأخبار في دليل changes في مستودع BeeWare. إذا كان هذا المجلد فارغًا، فمن المحتمل أن BeeWare قد نشرت مؤخرًا إصدارًا جديدًا؛ يتم حذف ملفات ملاحظات التغيير ودمجها لتحديث ملاحظات الإصدار مع كل إصدار. يمكنك الاطلاع على هذا الملف لمعرفة نمط التعليق المطلوب؛ يمكنك الاطلاع على طلبات السحب المدمجة مؤخرًا لمعرفة كيفية تنسيق ملاحظات التغيير الخاصة بك.

إرسال طلب سحب

الآن بعد أن قمت بتسجيل جميع التغييرات، أصبحت جاهزًا لتقديم طلب سحب. لضمان سير عملية المراجعة بسلاسة، هناك عدد من الخطوات التي يجب عليك اتخاذها.

العمل مع pre-commit

عندما تقوم بإجراء أي تغيير، سيتم تشغيل pre-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 بإصلاح المشكلة تلقائيًا؛ لذا يمكنك إعادة إضافة أي ملفات تم تعديلها نتيجة لفحوصات ما قبل الالتزام، وإعادة الالتزام بالتغيير. ومع ذلك، ستتطلب بعض الفحوصات إجراء تعديلات يدوية. بمجرد إجراء هذه التغييرات، أعد إضافة أي ملفات تم تعديلها، وأعد الالتزام.

(.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 الخاص بك عملية الالتزام كأحدث إضافة. أنت الآن جاهز للدفع إلى GitHub.

انقل التغييرات إلى GitHub وأنشئ طلب السحب الخاص بك

عندما تقوم بالدفع إلى GitHub لأول مرة، سيتم تزويدك بعنوان URL ينقلك مباشرة إلى صفحة GitHub لإنشاء طلب سحب جديد. اتبع عنوان 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

إذا كنت قد قمت مسبقًا بدفع الفرع الحالي إلى GitHub، فلن تتلقى عنوان URL مرة أخرى. ومع ذلك، هناك طرق أخرى للوصول إلى عنوان URL لإنشاء PR:

  • انتقل إلى المستودع الأصلي، وانقر على "طلبات السحب" ثم "طلب سحب جديد"، واختر من أين تريد إرسال طلب السحب.
  • إذا قمت بالدفع مؤخرًا، فانتقل إلى المستودع الأصلي، وحدد الشعار الموجود أعلى قائمة الملفات الذي يشير إلى أن المستودع "تلقى دفعات مؤخرًا"، ثم انقر على الزر "مقارنة وطلب سحب".
  • استخدم أمر GitHub CLI gh pr create، واملأ المطالبات.
  • استخدم أمر GitHub CLI gh pr create --web لفتح متصفح الويب على صفحة إنشاء PR.

أي من هذه الخيارات سيمكنك من إنشاء طلب سحب جديد.

واجهة CLI GitHub: gh

يوفر GitHub GitHub CLI، الذي يتيح لك الوصول إلى العديد من ميزات GitHub من جهازك الطرفي، من خلال الأمر gh. تغطي وثائق GitHub CLI جميع الميزات.

سحب محتوى الطلب

يجب أن يكون عنوان طلب السحب (pull request) غنيًا بالمعلومات وواضحًا وموجزًا. حاول أن تجعله قصيرًا إن أمكن، ولكن العناوين الأطول مقبولة إذا لزم الأمر. يجب أن يعطي عنوان PR الجيد لشخص لا يملك أي سياق فكرة معقولة عن الخطأ أو الميزة التي تم تنفيذها بواسطة PR الخاص بك.

يجب أن يعكس وصف PR بوضوح التغييرات التي طرأت على PR. يجب أن يتمكن أي شخص لا يعرف أي شيء عن السياق من قراءة الوصف الخاص بك، والحصول على فهم كامل نسبيًا لأسباب إجراء التغيير. تجنب النكات، والتعابير الاصطلاحية، واللغة العامية، والتنسيق غير الضروري، مثل استخدام الأحرف الكبيرة أو علامات الترقيم المفرطة؛ فالمقصود هو تقديم شرح مباشر لما يحدث في PR الخاص بك، وتجنب هذه الأشياء يجعل الوصف أكثر سهولة للآخرين.

إذا كانت هناك أي حالات إعادة إنتاج، أو أي نظام اختبار استخدمته ولم يتم تضمينه بالفعل في التغييرات الموجودة في PR، فيجب شرحها وإدراجها في PR. يجب أن يتضمن الشرح كيفية تشغيلها، وما يجب فعله لإعادة إنتاج النتيجة المرجوة.

إذا كان طلب السحب الخاص بك سيحل المشكلة رقم 1234، فيجب عليك تضمين النص "Fixes

1234" في وصف طلب السحب الخاص بك. سيؤدي ذلك إلى إغلاق المشكلة تلقائيًا عند دمج

طلب السحب. يمكنك الإشارة إلى مناقشات أو مشكلات أو طلبات سحب أخرى باستخدام نفس صيغة "#1234". يمكنك الإشارة إلى مشكلة في مستودع مختلف عن طريق إضافة علامة - قبل الرقم، على سبيل المثال، "python/cpython#1234" تشير إلى المشكلة 1234 في مستودع CPython.

التكامل المستمر

التكامل المستمر، أو CI، هو عملية إجراء فحوصات آلية على طلب السحب الخاص بك. يمكن أن يشمل ذلك فحوصات بسيطة مثل التأكد من صحة تنسيق الكود؛ ولكنه يشمل أيضًا تشغيل مجموعة الاختبارات وإنشاء الوثائق.

هناك العديد من التغييرات التي يمكن أن تؤدي إلى فشل CI. بشكل عام، لن نراجع أي طلب سحب (PR) لا يجتاز CI. إذا قمت بإنشاء طلب سحب وفشل CI، فلن نبدأ المراجعة حتى يجتاز. إذا أدت تغييراتك إلى فشل، فمن مسؤوليتك البحث عن السبب وحل المشكلة.

عند فشل CI، ستظهر روابط الفشل في أسفل صفحة PR، تحت عنوان "بعض الفحوصات لم تنجح". سترى قائمة بالفحوصات الفاشلة، والتي ستظهر في أعلى قائمة جميع الفحوصات إذا كانت هناك فحوصات ناجحة أيضًا. إذا نقرت على رابط الفشل، فسيأخذك إلى السجل. غالبًا ما يوفر السجل جميع المعلومات التي تحتاجها لمعرفة سبب الفشل. اقرأ السجل وحاول معرفة سبب حدوث الفشل، ثم قم بما هو ضروري لحله.

في بعض الأحيان، قد تفشل عملية فحص CI لأسباب لا علاقة لها بالتغييرات التي أجريتها. قد يكون ذلك بسبب مشكلة في الجهاز الذي يقوم بتشغيل فحص CI؛ أو لأن فحص CI غير مستقر. إذا لاحظت فشلًا، وكنت متأكدًا تمامًا أنه لا علاقة له بالتغييرات التي أجريتها، أضف تعليقًا إلى PR الخاص بك بهذا الشأن، وسنقوم بفحصه.

لبدء تشغيل CI جديد، تحتاج إلى دفع التغييرات الجديدة إلى فرعك.

إذا وجدت نفسك في موقف تحتاج فيه إلى المساعدة لتمرير CI، فاترك تعليقًا على PR لإعلامنا بذلك وسنبذل قصارى جهدنا لمساعدتك.

فحوصات pre-commit وtowncrier

إذا فشلت فحوصات pre-commit أو towncrier، فسيتم حظر تشغيل معظم فحوصات CI المتبقية. ستحتاج إلى حل المشكلات ذات الصلة قبل تشغيل مجموعة الفحوصات الكاملة.

لدينا موارد CI محدودة. من المهم أن تفهم أن CI سيبدأ في كل مرة تقوم فيها بالدفع إلى الفرع. إذا كنت تنوي إجراء عدد من التغييرات، فمن الأفضل إجراء هذه التغييرات محليًا، ودفعها جميعًا دفعة واحدة. سيتم تشغيل CI فقط على أحدث التزام في الدفعة، مما يقلل من الحمل على نظام CI لدينا.

لا تكتمل عملية تقديم طلبك للحصول على الإقامة الدائمة إلا بعد اجتيازه لفحص CI، أو يمكنك تقديم تفسير لسبب عدم اجتيازه.