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

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

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

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

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

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

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

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

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

macOSLinuxWindows

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

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

Python 3.8.10 (الإصدار الافتراضي، 20 يوليو 2020، الساعة 16:16:00)

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

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

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

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

Python 3.8.10 (الإصدار الافتراضي، 20 يوليو 2020، الساعة 16:16:00)

إذا كان لديك أكثر من إصدار واحد من 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 المقدم، واستخدمه لنسخ المستودع إلى جهاز الكمبيوتر الخاص بك باستخدام سطر الأوامر:

macOSLinuxWindows

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

$ git clone https://github.com/<اسم المستخدم الخاص بك>/beeware.git

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

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

$ git clone https://github.com/<اسم المستخدم الخاص بك>/beeware.git

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

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

C:\...>git clone https://github.com/<اسم المستخدم الخاص بك>/beeware.git

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

تعيين مستودع أعلى

بعد استنساخ الفرع الخاص بك، أضف مستودع BeeWare كمرجع بعيد upstream. هذا يمنح النسخة المستنسخة المحلية مرجعًا إلى المستودع الأصلي، مما يسهل مزامنة التحديثات بمرور الوقت.

ستحتاج أيضًا إلى علامات من upstream حتى تتمكن أدوات مثل Toga و Briefcase من تحديد أرقام الإصدارات بدقة:

macOSLinuxWindows

$ git remote add upstream https://github.com/beeware/beeware.git
$ git fetch --tags upstream

$ git remote add upstream https://github.com/beeware/beeware.git
$ git fetch --tags upstream

C:\...>git remote add upstream https://github.com/beeware/beeware.git
C:\...>git fetch --tags upstream

إذا كنت تريد أن تتضمن شوكتك هذه العلامات أيضًا، يمكنك دفعها:

$ git push --tags

قد يكون هذا مفيدًا إذا قمت بعمل نسخة جديدة لاحقًا وأردت أن تكون العلامات متاحة من شوكتك.

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

لإعداد بيئة افتراضية وترقية pip، قم بتشغيل:

macOSLinuxWindows

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

C:\...>cd beeware
C:\...>py -3 -m venv .venv
C:\...>.venv\Scripts\activate
(.venv) $ python -m pip install -U pip

يجب أن يكون أمام موجهك الآن بادئة (.venv).

تثبيت BeeWare

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

macOSLinuxWindows

(.venv) $ python -m pip install -U -e . --group dev

(.venv) $ python -m pip install -U -e . --group dev

(.venv) C:\...>python -m pip install -U -e . --group dev

تمكين الالتزام المسبق

BeeWare يستخدم أداة تسمى pre-commit لتحديد المشكلات البسيطة وتوحيد تنسيق الكود. ويقوم بذلك عن طريق تثبيت git hook الذي يقوم تلقائيًا بتشغيل سلسلة من أدوات فحص الكود قبل إنهاء أي git commit. لتمكين pre-commit، قم بتشغيل:

macOSLinuxWindows

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) C:\...>pre-commit install
pre-commit installed at .git/hooks/pre-commit

الآن أنت جاهز لبدء الاختراق على BeeWare!

العمل من فرع

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

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

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

بدلاً من ذلك، يجب إجراء التغييرات على فرع الميزة. يتميز فرع الميزة باسم بسيط لتعريف التغيير الذي قمت بإجرائه. على سبيل المثال، إذا كنت تقوم بإصلاح خطأ يسبب مشكلات في البناء على Windows 11، فيمكنك إنشاء فرع ميزة fix-win11-build. إذا كان الخطأ يتعلق بمشكلة محددة تم الإبلاغ عنها، فمن الشائع أيضًا الإشارة إلى رقم المشكلة في اسم الفرع (على سبيل المثال، fix-1234).

لإنشاء فرع ميزة fix-win11-build، قم بتشغيل:

macOSLinuxWindows

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

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

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

تجنب توسع نطاق العمل

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

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

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

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

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

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

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

سيتطلب إصلاح خطأ أو تنفيذ ميزة ما كتابة بعض الأكواد الجديدة.

لدينا دليل أسلوب كتابة الكود الذي يحدد إرشاداتنا الخاصة بكتابة الكود لـ BeeWare.

التطوير القائم على الاختبار

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

قم بتشغيل الكود الخاص بك

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

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

تشغيل الاختبارات والتغطية

يستخدم BeeWare tox لإدارة عملية الاختبار وpytest لمجموعة الاختبارات الخاصة به.

يتضمن الأمر الافتراضي tox تنفيذ ما يلي:

• خطافات ما قبل الالتزام
• towncrier التحقق من ملاحظات الإصدار

• فحص الأخطاء في الوثائق

• مجموعة الاختبارات لإصدارات Python المتاحة

• تقارير تغطية الكود

هذا هو ما تقوم به CI بشكل أساسي عند إرسال طلب سحب.

لتشغيل مجموعة الاختبارات الكاملة، قم بتنفيذ:

macOSLinuxWindows

(.venv) $ tox

(.venv) $ tox

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

قد يستغرق تشغيل مجموعة الاختبارات الكاملة بعض الوقت. يمكنك تسريع العملية بشكل كبير عن طريق تشغيل tox بشكل متوازٍ، وذلك بتشغيل tox p (أو tox run-parallel). عند تشغيل مجموعة الاختبارات بشكل متوازٍ، ستحصل على قدر أقل من المعلومات حول تقدم المجموعة أثناء تشغيلها، لكنك ستحصل مع ذلك على ملخص لأي مشكلات تم اكتشافها في نهاية عملية الاختبار. ومن المفترض أن تحصل على بعض النتائج التي تشير إلى أن الاختبارات قد تم تشغيلها. قد ترى اختبارات SKIPPED، ولكن لا ينبغي أن تحصل أبدًا على أي نتائج اختبار FAIL أو ERROR. نقوم بتشغيل مجموعة الاختبارات الكاملة قبل دمج كل تصحيح. إذا اكتشفت تلك العملية أي مشاكل، فإننا لا ندمج التصحيح. إذا وجدت خطأً أو فشلًا في الاختبار، فإما أن هناك شيئًا غريبًا في بيئة الاختبار الخاصة بك، أو أنك وجدت حالة استثنائية لم نرها من قبل - في كلتا الحالتين، أخبرنا بذلك!

بالإضافة إلى نجاح الاختبارات، من المفترض أن يُظهر هذا تغطية اختبار بنسبة 100٪.

تشغيل الاختبارات المختلفة

إجراء اختبارات على إصدارات متعددة من لغة Python

بشكل افتراضي، ستحاول العديد من أوامر tox تشغيل مجموعة الاختبارات عدة مرات، مرة لكل إصدار من إصدارات Python التي يدعمها BeeWare. ولكن للقيام بذلك، يجب أن تكون كل إصدارات Python مثبتة على جهازك ومتاحة لعملية [اكتشاف]tox Python الخاصة بـ (https://virtualenv.pypa.io/en/latest/explanation.html#python-discovery). وبشكل عام، إذا كان إصدار ما من Python متاحًا عبر PATH، فيجب أن يتمكن tox من العثور عليه واستخدامه.

تشغيل مجموعة الاختبارات فقط

إذا كنت تعمل على تطوير ميزة جديدة بوتيرة سريعة، فلست بحاجة إلى تشغيل مجموعة الاختبارات بالكامل؛ بل يمكنك تشغيل فقط اختبارات الوحدة. للقيام بذلك، قم بتشغيل:

macOSLinuxWindows

(.venv) $ tox -e py

(.venv) $ tox -e py

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

تشغيل مجموعة فرعية من الاختبارات

بشكل افتراضي، يقوم tox بتشغيل جميع الاختبارات الموجودة في مجموعة الاختبارات الوحدوية. عند تطوير اختبار جديد، قد يكون من المفيد تشغيل هذا الاختبار فقط. للقيام بذلك، يمكنك تمرير أي محدد pytest كحجة إلى tox. مسارات الاختبارات هذه نسبية بالنسبة إلى دليل briefcase. على سبيل المثال، لتشغيل الاختبارات الموجودة في ملف واحد فقط، قم بتشغيل:

macOSLinuxWindows

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) C:\...>tox -e py -- tests/path_to_test_file/test_some_test.py

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

تشغيل مجموعة الاختبارات لإصدار معين من لغة Python

بشكل افتراضي، سيتم تشغيل tox -e py باستخدام أي مترجم يتم تحديده على جهازك. إذا كان لديك عدة إصدارات من Python مثبتة، وترغب في اختبار إصدار معين من بين الإصدارات المثبتة، فيمكنك تحديد إصدار Python المراد استخدامه. على سبيل المثال، لتشغيل مجموعة الاختبارات على Python python, قم بتشغيل:

macOSLinuxWindows

(.venv) $ tox -e py310

(.venv) $ tox -e py310

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

يمكن تشغيل مجموعة فرعية من الاختبارات عن طريق إضافة -- ومواصفات الاختبار إلى سطر الأوامر.

تشغيل مجموعة الاختبارات دون تغطية (بسرعة)

بشكل افتراضي، سيقوم tox بتشغيل مجموعة اختبارات pytest في وضع الخيط الواحد. يمكنك تسريع تنفيذ مجموعة الاختبارات عن طريق تشغيلها بشكل متوازٍ. لا ينتج عن هذا الوضع ملفات تغطية بسبب التعقيدات التي تنطوي عليها عملية تسجيل التغطية داخل العمليات التي تم إنشاؤها. لتشغيل إصدار واحد من Python في الوضع "السريع"، قم بتشغيل:

macOSLinuxWindows

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

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

يمكن تشغيل مجموعة فرعية من الاختبارات عن طريق إضافة -- ومواصفات الاختبار إلى سطر الأوامر؛ ويمكن استخدام إصدار معين من Python عن طريق إضافة الإصدار إلى هدف الاختبار (على سبيل المثال، py310-fast للتشغيل السريع على Python 3.10).

تغطية الكود

يضمن BeeWare تغطية بنسبة 100% لجميع الفروع في قاعدة الكود. عند إضافة كود أو تعديله في المشروع، يجب عليك إضافة كود اختباري لضمان تغطية أي تغييرات تجريها.

ومع ذلك، يستهدف BeeWare منصات متعددة، بالإضافة إلى إصدارات متعددة من لغة Python، لذا لا يمكن التحقق من التغطية الكاملة على منصة واحدة وإصدار واحد من Python. ولتحقيق ذلك، تم تعريف عدة قواعد تغطية شرطية في قسم tool.coverage.coverage_conditional_plugin.rules من pyproject.toml (على سبيل المثال، يمكن استخدام no-cover-if-is-windows لتمييز كتلة من الكود لن يتم تنفيذها عند تشغيل مجموعة الاختبارات على Windows). تُستخدم هذه القواعد لتحديد أجزاء الكود التي يتم تغطيتها فقط على منصات معينة أو إصدارات Python معينة.

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

فهم نتائج التغطية

في نهاية مخرجات اختبار التغطية، يجب أن يظهر تقرير ببيانات التغطية التي تم جمعها:

الاسم    البيانات   الفروع المفقودة   نسبة المشاركة   التغطية   المفقود
 ---------------------------------------------------
 المجموع    7540 0   1040 0  100.0%

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

إذا أجريت تغييرات على قاعدة الكود، فمن المحتمل أن تتسبب في حدوث فجوة في التغطية. وعندما يحدث ذلك، سيُعلمك تقرير التغطية بالأسطر التي لم يتم تنفيذها. على سبيل المثال، لنفترض أننا أجرينا تغييرًا على some/interesting_file.py، بإضافة بعض المنطق الجديد. قد يبدو تقرير التغطية كما يلي:

الاسم   العبارات   الخطأ   الفرع   الجزء   التغطية   المفقود
 -------------------------------------------------------------------------------
 src/some/interesting_file.py 111 1     26 0  98.1%   170، 302-307، 320->335
 -------------------------------------------------------------------------------
 المجموع 7540 1   1726 0  99.9%

هذا يشير إلى أن السطر 170، والأسطر من 302 إلى 307، والانتقال من السطر 320 إلى السطر 335، لا يتم تنفيذها من قِبل مجموعة الاختبارات. ستحتاج إلى إضافة اختبارات جديدة (أو تعديل اختبار موجود) لاستعادة هذه التغطية.

تقرير التغطية الخاص بالمنصة المضيفة وإصدار لغة Python

يمكنك إنشاء تقرير تغطية لمنصة Python وإصدارها. على سبيل المثال، لتشغيل مجموعة الاختبارات وإنشاء تقرير تغطية على Python 3.10, قم بتشغيل:

macOSLinuxWindows

(.venv) $ tox -m test310

(.venv) $ tox -m test310

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

تقرير التغطية الخاص بالمنصة المضيفة

إذا كانت جميع إصدارات Python المدعومة متاحة لـ tox, فيمكن الإبلاغ عن التغطية الخاصة بمنصة المضيف عن طريق تشغيل:

macOSLinuxWindows

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

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

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

تقرير التغطية بتنسيق HTML

يمكن إنشاء تقرير تغطية HTML بإضافة -html إلى أي من أسماء بيئات التغطية tox، على سبيل المثال:

macOSLinuxWindows

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

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

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

الأمر لا يقتصر على كتابة الاختبارات فحسب!

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

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

بناء الوثائق

قبل إجراء أي تغييرات على وثائق BeeWare, من المفيد التأكد من أنه يمكنك إنشاء الوثائق الموجودة.

يجب أن يكون مترجم Python 3.13 مثبتًا ومتاحًا في مسارك (أي أن python3.13 يجب أن يبدأ مترجم Python 3.13).

BeeWare يستخدم tox لإنشاء الوثائق. يجب تشغيل أوامر tox التالية من نفس موقع ملف tox.ini، الموجود في الدليل الجذر للمشروع.

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

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

سيتم إنشاء المعاينة المباشرة مع ظهور تحذيرات!

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

يختلف "التحذير" عن "الخطأ". إذا أدخلت مشكلة تعتبر "خطأ"، فسوف يفشل الخادم المباشر، وسيتطلب إعادة التشغيل. ولن يعمل مرة أخرى حتى يتم حل مشكلة "التحذير".

لبدء تشغيل الخادم المباشر:

macOSLinuxWindows

(venv) $ tox -e docs-live

(venv) $ tox -e docs-live

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

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

بمجرد بدء تشغيل الخادم، سترى شيئًا مثل ما يلي في إخراج وحدة التحكم:

معلومات    -  [11:18:51] يتم تقديم الخدمة على http://127.0.0.1:8000/

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

docs-live هي خطوة أولية

يُقصد بتشغيل docs-live للعمل مع الخادم المباشر إجراء التكرار الأولي. يجب عليك دائمًا تشغيل بنية محلية قبل إرسال طلب سحب.

بناء محلي

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

إنشاء بنية محلية

لإنشاء بنية محلية:

macOSLinuxWindows

(venv) $ tox -e docs

(venv) $ tox -e docs

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

سيكون ناتج هذا البناء في دليل _build في جذر المشروع.

إنشاء نسخة مترجمة محلية

تمت ترجمة وثائق BeeWare إلى عدة لغات. قد تؤدي تحديثات الوثائق باللغة الإنجليزية إلى حدوث مشكلات في الإصدارات باللغات الأخرى. من المهم التحقق من أن جميع الإصدارات تعمل بشكل صحيح قبل إرسال طلب سحب.

لإنشاء نسخة من جميع الترجمات المتاحة:

macOSLinuxWindows

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

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

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

سيكون ناتج كل بناء لغة في الدليل المرتبط _build/html/<languagecode>، حيث <languagecode> هو رمز اللغة المكون من حرفين أو خمسة أحرف المرتبط باللغة المحددة (على سبيل المثال fr للفرنسية، it للإيطالية، إلخ).

إذا وجدت مشكلة في بنية واحدة، يمكنك تشغيل تلك البنية بشكل منفصل عن طريق تشغيل tox -e docs-<languagecode>. على سبيل المثال، لتكوين الوثائق باللغة الفرنسية فقط، قم بتشغيل:

macOSLinuxWindows

(venv) $ tox -e docs-fr

(venv) $ tox -e docs-fr

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

سيكون ناتج البناء أحادي اللغة في دليل _build.

توثيق linting

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

macOSLinuxWindows

(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 إذا رأيت مسارًا بديلًا مدرجًا. على سبيل المثال:

- ./مسار/إلى/المجلد/*

إذا كان القسم الذي تنوي تضمين new_doc.md فيه عبارة عن قائمة من روابط Markdown الفردية، فستحتاج إلى إضافة رابط صريح إلى رابطك. على سبيل المثال:

- [مستندي الجديد](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:

macOSLinuxWindows

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) C:\...>git add some/interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

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

macOSLinuxWindows

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) C:\...>git add some\interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

بمجرد اكتمال كل شيء، ستظهر رسالة تشير إلى أن عملية الالتزام قد اكتملت، وسيظهر سجل git الخاص بك عملية الالتزام كأحدث إضافة. أنت الآن جاهز للدفع إلى GitHub.

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

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

فيما يلي مثال على ما يمكن توقعه عند الضغط على "push"، مع تمييز عنوان URL.

macOSLinuxWindows

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) C:\...>git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

إذا كنت قد قمت مسبقًا بدفع الفرع الحالي إلى 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، أو يمكنك تقديم تفسير لسبب عدم اجتيازه.