إصلاح مشكلة¶
BeeWare يتتبع قائمة المشكلات المعروفة. أي من هذه المشكلات هي مرشحة للعمل عليها.
يمكن تصفية هذه القائمة بعدة طرق. على سبيل المثال، يمكنك التصفية حسب النظام الأساسي، بحيث يمكنك التركيز على المشكلات التي تؤثر على الأنظمة الأساسية التي يمكنك اختبارها؛ أو يمكنك التصفية حسب نوع المشكلة، مثل أخطاء التوثيق. هناك أيضًا تصفية لـ المشكلات الجيدة الأولى - وهي المشكلات التي تم تحديدها على أنها مشكلات ذات أسباب معروفة، ونعتقد أن إصلاحها ينبغي أن يكون سهلاً نسبيًا (على الرغم من أننا قد نكون مخطئين في تحليلنا).
إذا كان عمر المشكلة أكثر من 6 أشهر، فمن المحتمل جدًا أن تكون قد تم حلها، لذا فإن الخطوة الأولى هي التحقق من إمكانية إعادة إنتاج المشكلة. استخدم المعلومات الواردة في تقرير الخطأ لمحاولة إعادة إنتاج المشكلة. إذا لم تتمكن من إعادة إنتاج المشكلة، فقم بالإبلاغ عما وجدته كتعليق على المشكلة، واختر مشكلة أخرى.
إذا تمكنت من إعادة إنتاج المشكلة - فحاول إصلاحها! اكتشف مجموعة الأكواد التي تنفذ الميزة، وحاول معرفة ما الذي لا يعمل بشكل صحيح.
حتى إذا لم تتمكن من حل المشكلة، فإن الإبلاغ عن أي شيء تكتشفه أثناء العملية كتعليق على المشكلة أمر يستحق العناء. إذا تمكنت من العثور على مصدر المشكلة، ولكن لم تتمكن من إيجاد حل لها، فغالبًا ما تكون هذه المعرفة كافية لشخص أكثر دراية بالمنصة لحل المشكلة. إذا لم توفر المشكلة بالفعل حالة إعادة إنتاج جيدة (تطبيق عينة صغير لا يفعل شيئًا سوى إعادة إنتاج المشكلة)، فإن توفير واحدة يمكن أن يكون مفيدًا للغاية.
المساهمة في إصلاح مشكلة¶
إعداد بيئة التطوير
للمساهمة في 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
إعادة إنتاج المشكلة
لا يمكنك حل مشكلة ما إذا لم تكن لديك هذه المشكلة في المقام الأول. لذلك، فإن إعادة إنتاج المشكلة هو شرط أساسي لحلها. في البرمجيات، يشار إلى المشاكل عادةً باسم "أخطاء"، وغالبًا ما تسمى المشاكل "تقارير الأخطاء".
أحدهم قدم تقريرًا عن خطأ. عليك التحقق من أن الخطوات التي وصفها المبلغ تؤدي إلى حدوث الخطأ المبلغ عنه. هل يمكنك إعادة إنتاج النتيجة نفسها من خلال القيام بما هو موصوف في التقرير بالضبط؟ إذا لم تتمكن من ذلك، عليك معرفة السبب.
أخطاء في الكود¶
في الحالة المثالية، سيكون لديك نفس الإعدادات التي لدى الشخص الذي أبلغ عن الخطأ، وستتبع الخطوات، وستتمكن من إعادة إنتاج الخطأ كما هو موصوف. لكن في كثير من الحالات، لن يكون الأمر بهذه البساطة. تتضمن العديد من تقارير الأخطاء تفسيرات غامضة ومجموعة غامضة من الشروط. تكمن المشكلة في أن العديد من الأخطاء تختلف بناءً على مجموعة الشروط ذات الصلة، بما في ذلك كيفية التفاعل معها، والشروط المسبقة المختلفة، ونظام التشغيل، وإصدار نظام التشغيل، وبنية وحدة المعالجة المركزية، أو ما إذا كان جهاز المستخدم قديمًا وبطيئًا أم جديدًا وسريعًا. كلما زادت المعلومات المتوفرة لدينا حول الموقف المحيط بالخطأ، كان ذلك أفضل. حاول إعادة إنتاج مجموعة الشروط التي قدمها المبلغ. إذا لم تتمكن من القيام بذلك، فقد تحتاج في الخطوة التالية إلى طلب مزيد من المعلومات من الشخص الذي أبلغ عن الخطأ.
أفضل طريقة لإعادة إنتاج خطأ ما هي باستخدام أصغر مثال ممكن لا يزال يظهر المشكلة. في معظم الأحيان، لا يقدم المبلغون مثالاً عملياً أدنى؛ وإذا قدموا أي مثال على الإطلاق، فسيتم نسخه مباشرة من تطبيقهم "الواقعي". سيكون هدفك هو تقليل التقرير إلى أبسط شكل ممكن يظهر المشكلة. أفضل حالة لإعادة إنتاج الخطأ هي أصغر برنامج ممكن. هذا التخفيض مفيد في حد ذاته لأنه يحدد ماهية المشكلة الفعلية. يمكن لأي شخص أن يأخذ المثال البسيط ويقوم بتشغيله، وسيلاحظ الخطأ الموصوف.
أخطاء في الوثائق¶
يمكن أن تظهر الأخطاء في الوثائق بطرق مختلفة. هناك مشاكل في التنسيق تؤدي إلى مشاكل في العرض. في بعض الأحيان، قد لا يكون الأمر خطأً برميًا؛ فقد يكون الشخص قد أخطأ في قراءة الوثائق أو ارتكب خطأً حقيقيًا. هذا لا يعني بالضرورة أنه لا توجد مشكلة في الوثائق. قد يكون المحتوى غير واضح أو غير دقيق، مما يترك مجالًا للالتباس أو سوء التفسير. من الممكن أن يكون هناك مفهوم يجب مناقشته ولم تتم مناقشته، لأنه غير موثق تمامًا.
عندما يتم الإبلاغ عن خطأ في الوثائق، يجب عليك التحقق من أن المشكلة المبلغ عنها لا تزال موجودة بالفعل. في حالة مشاكل العرض، ستحتاج إلى إنشاء الوثائق لترى ما إذا كان بإمكانك إعادة إنتاج المشكلة. مشاكل المحتوى هي مسألة قراءة للتحقق من عدم قيام أي شخص بتقديم تحديث.
تحديث المشكلة¶
الخطوة الأخيرة في عملية الفرز هي توثيق النتائج التي توصلت إليها عن طريق ترك تعليق على المشكلة.
إذا تمكنت من إعادة إنتاج المشكلة تمامًا كما هو موصوف، فهذا كل ما عليك قوله. اترك تعليقًا تفيد فيه أنك تأكدت من أنك تواجه نفس المشكلة، بالطريقة نفسها التي وصفها المبلغ الأصلي.
إذا كان بإمكانك تقديم أي سياق إضافي، فقم بتضمين تفاصيل هذا السياق. قد يشمل ذلك القدرة على إعادة إنتاج المشكلة على نظام تشغيل مختلف، أو باستخدام إصدار مختلف من بعض البرامج المعنية، أو أي شيء آخر يختلف عن التقرير الأصلي.
إذا كان التقرير الأصلي يفتقد إلى التفاصيل التي تحتاجها لإعادة إنتاج التقرير، فقم بتضمين تلك التفاصيل. قد يشمل ذلك توفير تفاصيل نظام التشغيل أو الإصدار التي لم يذكرها التقرير الأصلي، أو سجلات أو تتبعات مكدس أكثر اكتمالاً، أو تعليمات أوضح حول التسلسل الدقيق للعمليات اللازمة لإعادة إنتاج المشكلة. إذا كنت قد طورت طريقة أبسط لإعادة إنتاج المشكلة (أو لم يقدم المبلغ الأصلي حالة إعادة إنتاج)، فيمكنك تضمين تفاصيل منهجية إعادة الإنتاج تلك.
إذا لم تتمكن من إعادة إنتاج المشكلة، فقم أيضًا بترك تعليق يوضح بالتفصيل ما قمت بتجربته. إن معرفة أين لا توجد المشكلة لا يقل أهمية عن معرفة أين توجد المشكلة، لأن ذلك يساعد في تضييق نطاق الأسباب المحتملة. إذا كانت لديك أي نظريات حول سبب عدم قدرتك على إعادة إنتاج المشكلة - على سبيل المثال، إذا كنت تعتقد أنها خطأ في الاستخدام، أو أن المشكلة قد تم حلها من خلال تحديث نظام التشغيل الأخير - فقم بتضمين هذا التخمين كجزء من تعليقك.
أخيرًا، يمكنك تقديم أي توصيات قد تكون لديك إلى الفريق الأساسي. إذا كنت تعتقد أن التقرير الأصلي يحتوي على خطأ، فاقترح إغلاق المشكلة؛ وإذا كانت لديك نظرية حول سبب المشكلة، فيمكنك اقتراحها أيضًا. ستساعد تعليقاتك الفريق الأساسي على تحديد كيفية المضي قدمًا في المشكلة إلى الخطوة التالية.
إذا كان حل المشكلة يتطلب تغييرات في الكود:
كتابة الكود وتشغيله واختباره
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
----------------------------------------------------
المجموع 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.md789.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، أو يمكنك تقديم تفسير لسبب عدم اجتيازه.