استخدام الأدوات¶
أحد أهم التعليقات التي يمكننا الحصول عليها هي تلك التي تأتي من الأشخاص الذين يحاولون استخدام أدوات BeeWare ويكتشفون وجود نقطة خلاف أو ميزة مفقودة. من المفيد للغاية بالنسبة لنا أن نفهم أي صعوبات قد تواجهها عند استخدام الأدوات لأغراض عملية.
فكر في الشيء الذي لطالما أردت بناءه، وحاول بناءه. إذا تبين أنك قادر على بناء مشروعك، فتهانينا! لقد حصلت على الشيء الذي لطالما أردته.
ومع ذلك، إذا لم تنجح في ذلك، فأخبرنا بما حدث. هل كانت هناك ميزة مفقودة؟ هل الوثائق مربكة أو ناقصة في بعض الجوانب؟ إن مشاركة تجربتك تمنحنا رؤية مفيدة يمكننا استخدامها لتشكيل عملية التخطيط لدينا.
إذا واجهت أي مشاكل، فابدأ موضوع نقاش جديد، فقد يكون ذلك بداية لمشكلة جديدة أو اقتراح لميزة جديدة.
استخدام أدوات المساهمة¶
إرسال مشكلة جديدة
كتابة تقرير جيد عن المشكلة أو الخطأ يمكن أن يحدث فرقًا كبيرًا في القدرة على حل المشكلة. إليك كيفية إرسال تقرير جيد عن الخطأ إلى 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>
بعد تقديم أكبر قدر ممكن من المعلومات، انقر على "إنشاء" لإرسال التقرير.
اقتراح ميزة جديدة
لديك فكرة حول تحسين BeeWare - كيف يمكنك تقديم هذه الفكرة للنظر فيها؟
قم ببحثك¶
الخطوة الأولى هي البحث في متتبع المشكلات BeeWare عن مشكلات الميزات (المشكلات التي تحمل علامة "تحسين"), مشكلات التوثيق (المشكلات التي تحمل علامة "توثيق"), أو مواضيع المناقشة لمعرفة ما إذا كانت الفكرة قد تم اقتراحها من قبل. إذا كان الأمر كذلك، وكان لديك سياق أو أفكار جديدة تود إضافتها، فقم بتضمينها في سلسلة المناقشة الحالية. إذا كنت ترغب في الحصول على مساعدة في بحثك، يمكنك أن تطلبها في قناة #dev على BeeWare Discord. قد نتمكن من توجيهك إلى سلاسل المناقشة الحالية، أو تزويدك بسياق قد لا تكون على دراية به، أو ربط فكرتك بفكرة أخرى قد لا تبدو ذات صلة في البداية.
ناقش الفكرة¶
إذا لم تجد أي مراجع موجودة لفكرتك، فابدأ موضوع نقاش. قدم وصفًا عامًا للغرض من فكرتك وحالة استخدامها. أدرج أي أفكار لديك حول الشكل الذي ستبدو عليه الميزة، إذا تم تنفيذها، مثل الشكل العام لواجهة برمجة التطبيقات (API) أو المظهر المرئي لإحدى القدرات أو المستند الذي سيتم إضافته. إذا كان ذلك مناسبًا، يجب عليك أيضًا تضمين أي أبحاث قمت بها حول كيفية ظهور فكرتك على منصات مختلفة.
بمجرد فتح موضوع المناقشة، سيقوم فريق BeeWare وبقية أعضاء المجتمع بالرد. سيهدف الفريق الأساسي إلى تقديم انطباع أولي على الأقل عن فكرتك في غضون يومي عمل. إذا كانت الفكرة معقدة بشكل خاص، فقد يستغرق التحليل الأكثر تفصيلاً ما يصل إلى أسبوع. قد تؤدي الأحداث مثل العطلات والمؤتمرات إلى إطالة هذه المدة قليلاً.
هذه هي فرصتك للمشاركة في محادثة حول فكرتك. قد نطلب منك مزيدًا من التفاصيل أو السياق. قد يشارك أعضاء آخرون من المجتمع في المناقشة، ويقدمون وجهات نظر أخرى أو اقتراحات أو مقترحات مضادة. ستحدد نتيجة هذه المناقشة الخطوات التالية.
من المهم أن تفهم أن ليس كل الأفكار ستُقبل. السبب في أن هذه العملية تبدأ بتقديم اقتراح هو لتجنب بذل كل هذا الجهد، لتكتشف في النهاية أن هناك سببًا لعدم قبول التغيير الذي اقترحته.
هذا لا يعني أنها لم تكن فكرة جيدة! قد تكون هناك أسباب فنية تمنع تنفيذها. على سبيل المثال، قد نرفض فكرة ما إذا:
- سيكون من الصعب أو المستحيل تنفيذه بشكل موثوق عبر جميع الأنظمة الأساسية المدعومة؛ أو
- سيكون من الصعب صيانتها، أو ستتطلب الصيانة الوصول إلى تكنولوجيا أو برامج غير متوفرة على نطاق واسع؛ أو
- إنه يخدم جمهورًا متخصصًا، ولكنه يفرض أعباء كبيرة على المستخدمين الآخرين.
إذا قررنا أن فكرتك غير مناسبة، فهذا لا يعني بالضرورة أنك يجب أن تتخلى عنها. على الرغم من أننا قد نرفض فكرة محددة، إلا أننا قد نكون أكثر استعدادًا لإضافة واجهة مكون إضافي أو نقطة تمديد أخرى تسمح لك بالحفاظ على نفس الميزة كمكتبة خارجية. بهذه الطريقة، يمكنك الحصول على الميزة، ولكن دون المخاوف المحددة المتعلقة بالصيانة أو القيود التي تفرضها الميزة على المشروع نفسه.
تحويل إلى طلب ميزة رسمي¶
بمجرد أن تصل المناقشة إلى توافق في الآراء حول شكل الميزة، يمكنك إنشاء [مشكلة طلب ميزة] جديدة (https://github.com/beeware/beeware/issues/new/choose) في متتبع المشكلات BeeWare، والتي تلخص المناقشة، مع ربطها بالمناقشة للحصول على السياق.
ليس عليك تنفيذ اقتراح الميزة بنفسك؛ يمكنك فتح مشكلة مع تفاصيل ما تقترحه. ومع ذلك، فإن مجرد نشر المشكلة لا يعني أنها ستنفذ من أجلك. ستحتاج إلى الانتظار حتى يتم اختيارها من قبل شخص آخر مهتم بنفس الميزة، سواء كان ذلك عضوًا آخر في المجتمع أو الفريق الأساسي؛ ولكن هذا ليس مضمونًا. إذا كنت تريد ضمان التنفيذ، فستحتاج إلى تنفيذه بنفسك، أو دفع المال لشخص آخر لتنفيذه نيابة عنك.