إرسال مشكلة جديدة¶

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

البحث عن المشكلات الحالية¶

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

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

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

ابدأ بمناقشة¶

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

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

كتابة تقرير جيد عن الأخطاء¶

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

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

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

إصدار نظام التشغيل الخاص بك - حتى الإصدار المصغر (على سبيل المثال، macOS 15.7.2).
إصدار Python الخاص بك، بما في ذلك الإصدار الفرعي (على سبيل المثال، 3.14.1).
كيف قمت بتثبيت Python. هل قمت بتنزيله من python.org؟ هل استخدمت Homebrew؟ uv؟ pyenv؟ conda؟ شيء آخر؟
الإصدار المحدد من أدوات BeeWare الذي تستخدمه (على سبيل المثال، Toga 0.5.3). إذا كنت تستخدم إصدارًا تجريبيًا، فما هو Git hash الذي تستخدمه؟ لا يكفي أن تقول "الفرع الرئيسي الحالي"، لأن ذلك يمكن أن يتغير يوميًا.
الإصدارات المحددة من الحزم الأخرى التي يجب تثبيتها لإحداث المشكلة. يمكنك تضمين نتائج تشغيل python -m pip freeze لتوفير هذه المعلومات.
إذا تم إنشاء ملف سجل، فإن ملف السجل بالكامل.
إذا تم إنشاء تتبع المكدس، فقم بتوفير كامل تتبع المكدس. لا تكتفِ بتوفير رسالة الخطأ النهائية - فمن المهم توفير السياق الكامل لتتبع المكدس. ومن الأفضل أيضًا توفير ذلك في شكل نص، وليس كصورة شاشة.
أي شيء آخر يتعلق بإعدادات الكمبيوتر أو الشبكة قد يكون له تأثير على المشكلة. هل الكمبيوتر قديم أو بطيء؟ هل هو جهاز عمل قد يكون مزودًا ببرامج حماية أو برامج فحص فيروسات أو قيود أخرى؟ هل الشبكة بطيئة بشكل خاص؟ هل تشغل نظام التشغيل بإعدادات افتراضية غير عادية (مثل خط كبير جدًا أو بعض التقنيات المساعدة الأخرى الممكّنة)؟

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

مثال بسيط¶

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

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

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

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

تقديم التقرير¶

انتقل إلى قائمة مشكلات المشروع، وانقر على زر "مشكلة جديدة"، واختر "تقرير خطأ" لبدء العملية.

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

عند تضمين كود، في حالة إمكانية إعادة إنتاجه باستخدام مثال موجود، مثل دليل BeeWare التعليمي، يمكنك توفير رابط. خلاف ذلك، قم بتوفير الكود في التقرير. يجب أن يكون بتنسيق Markdown؛ يحتاج الكود إلى ثلاثة علامات اقتباس مائلة (```) قبله وبعده.

إذا كنت بحاجة إلى تضمين كتلة نصية طويلة، يمكنك جعلها محتوى مطويًا باستخدام الصيغة التالية:

<details>
<summary>Collapsed content title</summary>
Long block of text.
</details>

بعد تقديم أكبر قدر ممكن من المعلومات، انقر على "إنشاء" لإرسال التقرير.