إصلاح مشكلة

BeeWare يتتبع قائمة المشكلات المعروفة. أي من هذه المشكلات هي مرشحة للعمل عليها.

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

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

إذا تمكنت من إعادة إنتاج المشكلة - فحاول إصلاحها! اكتشف مجموعة الأكواد التي تنفذ الميزة، وحاول معرفة ما الذي لا يعمل بشكل صحيح.

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

المساهمة في إصلاح مشكلة

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

للمساهمة في 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

إعادة إنتاج المشكلة

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

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

أخطاء في الكود

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

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

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

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

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

تحديث المشكلة

الخطوة الأخيرة في عملية الفرز هي توثيق النتائج التي توصلت إليها عن طريق ترك تعليق على المشكلة.

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

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

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

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

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

إذا كان حل المشكلة يتطلب تغييرات في الكود:

كتابة الكود وتشغيله واختباره

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

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