سواءً كنتَ تُضيف دالة خسارة، أو تُحسّن تغطية الاختبار، أو تكتب طلب تعليقات لتغيير تصميمي جوهري، فإن هذا الجزء من دليل المساهمين سيساعدك على البدء. شكرًا لك على عملك واهتمامك بتحسين TensorFlow.
قبل أن تبدأ
قبل المساهمة في مشروع TensorFlow، يُرجى مراجعة ملف CONTRIBUTING.md الموجود في مستودع المشروع على GitHub. على سبيل المثال، راجع ملف CONTRIBUTING.md في مستودع TensorFlow الأساسي. يُشترط على جميع المساهمين في الكود توقيع اتفاقية ترخيص المساهم (CLA).
لتجنب تكرار العمل، يُرجى مراجعة طلبات التعليقات الحالية أو المقترحة والتواصل مع المطورين عبر منتديات TensorFlow ( developers@tensorflow.org ) قبل البدء في العمل على أي ميزة معقدة. نحن نختار بعناية عند إضافة وظائف جديدة، وأفضل طريقة للمساهمة في المشروع ودعمه هي العمل على حل المشكلات المعروفة.
مشاكل للمساهمين الجدد
ينبغي على المساهمين الجدد البحث عن الوسوم التالية عند البحث عن أول مساهمة لهم في قاعدة بيانات TensorFlow. نوصي بشدة أن يبدأ المساهمون الجدد بمشاريع "مشكلة أولى جيدة" و"مساهمات مرحب بها"؛ فهذا يساعدهم على التعرف على آلية المساهمة، كما يتيح للمطورين الأساسيين فرصة التعرف عليهم.
إذا كنت مهتمًا بتشكيل فريق للمساعدة في معالجة مشكلة واسعة النطاق أو ميزة جديدة، فيرجى إرسال بريد إلكتروني إلى developers@group ومراجعة قائمتنا الحالية لطلبات التعليقات (RFCs).
مراجعة الكود
تخضع الميزات الجديدة وإصلاحات الأخطاء وأي تغييرات أخرى في قاعدة التعليمات البرمجية لمراجعة التعليمات البرمجية.
تُعدّ مراجعة الشيفرة البرمجية المُساهم بها في المشروع عبر طلبات السحب عنصرًا أساسيًا في تطوير TensorFlow. نشجع الجميع على البدء بمراجعة الشيفرة البرمجية المُقدّمة من مطورين آخرين، لا سيما إذا كانت الميزة من الأمور التي يُحتمل استخدامها.
فيما يلي بعض الأسئلة التي يجب مراعاتها أثناء عملية مراجعة الكود:
- هل نرغب في إضافة هذه الميزة إلى TensorFlow؟ هل يُحتمل استخدامها؟ هل تُعجبك، كمستخدم لـ TensorFlow، هذه الميزة وتعتزم استخدامها؟ هل تندرج هذه الميزة ضمن نطاق TensorFlow؟ هل ستكون تكلفة صيانة هذه الميزة الجديدة مُبررةً لفوائدها؟
- هل يتوافق الكود مع واجهة برمجة تطبيقات TensorFlow؟ هل الدوال والفئات والمعاملات العامة مُسماة بشكل جيد ومصممة بشكل بديهي؟
هل يتضمن توثيقًا؟ هل جميع الدوال العامة، والفئات، والمعاملات، وأنواع الإرجاع، والخصائص المخزنة مُسماة وفقًا لمعايير TensorFlow وموثقة بشكل واضح؟ هل الوظائف الجديدة موصوفة في توثيق TensorFlow وموضحة بأمثلة كلما أمكن؟ هل يتم عرض التوثيق بشكل صحيح؟
هل الكود سهل القراءة؟ هل هو قليل التكرار؟ هل ينبغي تحسين أسماء المتغيرات لزيادة الوضوح والاتساق؟ هل ينبغي إضافة تعليقات؟ هل ينبغي حذف أي تعليقات غير مفيدة أو زائدة؟
هل الكود فعال؟ هل يمكن إعادة كتابته بسهولة ليعمل بكفاءة أكبر؟
هل الكود متوافق مع الإصدارات السابقة من TensorFlow؟
هل سيضيف الكود الجديد تبعيات جديدة على مكتبات أخرى؟
اختبار وتحسين تغطية الاختبار
يُعدّ اختبار الوحدات عالي الجودة حجر الزاوية في عملية تطوير TensorFlow. ولتحقيق هذا الغرض، نستخدم صور Docker. تُسمى دوال الاختبار بأسماء مناسبة، وهي مسؤولة عن التحقق من صحة الخوارزميات وخيارات الكود المختلفة.
يجب أن تتضمن جميع الميزات الجديدة وإصلاحات الأخطاء تغطية اختبارية كافية. كما نرحب بمساهماتكم في إضافة حالات اختبار جديدة أو تحسين الاختبارات الحالية. إذا اكتشفتم أن اختباراتنا الحالية غير مكتملة - حتى لو لم يكن ذلك سببًا لظهور خطأ حاليًا - يُرجى الإبلاغ عن المشكلة، وإذا أمكن، تقديم طلب سحب.
للاطلاع على التفاصيل المحددة لإجراءات الاختبار في كل مشروع من مشاريع TensorFlow، راجع ملفي README.md و CONTRIBUTING.md في مستودع المشروع على GitHub.
من بين المخاوف الخاصة المتعلقة بالاختبار الكافي :
- هل يتم اختبار كل دالة وفئة عامة ؟
- هل تم اختبار مجموعة معقولة من المعايير وقيمها وأنواعها وتراكيبها؟
- هل تؤكد الاختبارات صحة الكود ، وأنه يقوم بما تنص عليه الوثائق ؟
- إذا كان التغيير عبارة عن إصلاح لخلل برمجي، فهل يتضمن اختبارًا للتأكد من عدم حدوث تراجع في الأداء ؟
- هل تجتاز الاختبارات عملية البناء المستمر ؟
- هل تغطي الاختبارات كل سطر من التعليمات البرمجية؟ إذا لم يكن الأمر كذلك، فهل الاستثناءات معقولة وواضحة؟
إذا واجهت أي مشاكل، فيرجى التفكير في مساعدة المساهم على فهم تلك المشاكل وحلها.
تحسين رسائل الخطأ أو سجلات الأخطاء
نرحب بالمساهمات التي تُحسّن رسائل الخطأ والتسجيل.
سير عمل المساهمة
تتم جميع المساهمات البرمجية - من إصلاح الأخطاء وتطويرات جديدة وتحسينات للاختبارات - عبر آلية عمل مركزية على منصة GitHub. للمشاركة في تطوير TensorFlow، أنشئ حسابًا على GitHub. ثم:
أنشئ نسخة من المستودع الذي تنوي العمل عليه. انتقل إلى صفحة مستودع المشروع واستخدم زر "إنشاء نسخة ". سيؤدي هذا إلى إنشاء نسخة من المستودع باسم المستخدم الخاص بك. (للحصول على مزيد من التفاصيل حول كيفية إنشاء نسخة من مستودع، راجع هذا الدليل .)
قم بنسخ المستودع إلى نظامك المحلي.
$ git clone git@github.com:your-user-name/project-name.gitأنشئ فرعًا جديدًا لحفظ أعمالك.
$ git checkout -b new-branch-nameاعمل على الكود الجديد. اكتب الاختبارات وقم بتشغيلها.
قم بتأكيد التغييرات.
$ git add -A$ git commit -m "commit message here"قم برفع التغييرات إلى مستودع GitHub الخاص بك.
$ git push origin branch-nameافتح طلب سحب (PR). انتقل إلى مستودع المشروع الأصلي على GitHub. ستظهر لك رسالة بخصوص الفرع الذي قمتَ برفعه مؤخرًا، تسألك عما إذا كنت ترغب في فتح طلب سحب. اتبع التعليمات، وقارن التغييرات بين المستودعات ، ثم أرسل طلب السحب. سيؤدي هذا إلى إرسال بريد إلكتروني إلى المساهمين. قد ترغب أيضًا في إرسال بريد إلكتروني إلى القائمة البريدية لزيادة وضوح التغييرات. (للمزيد من التفاصيل، راجع دليل GitHub حول طلبات السحب ).
سيقوم المشرفون والمساهمون الآخرون بمراجعة طلب السحب الخاص بك . يُرجى المشاركة في النقاش، ومحاولة إجراء أي تغييرات مطلوبة . بمجرد الموافقة على طلب السحب، سيتم دمج الكود.
قبل البدء في العمل على مساهمتك التالية ، تأكد من أن مستودعك المحلي محدّث.
قم بإعداد جهاز التحكم عن بعد الرئيسي. (يكفي القيام بذلك مرة واحدة لكل مشروع، وليس في كل مرة.)
$ git remote add upstream git@github.com:tensorflow/project-repo-nameانتقل إلى الفرع الرئيسي المحلي.
$ git checkout masterقم بتنزيل التغييرات من المصدر الرئيسي.
$ git pull upstream masterقم برفع التغييرات إلى حسابك على GitHub. (اختياري، ولكنه ممارسة جيدة.)
$ git push origin masterأنشئ فرعًا جديدًا إذا كنت تبدأ عملًا جديدًا.
$ git checkout -b branch-name
موارد إضافية git و GitHub:
قائمة التحقق الخاصة بالمساهمين
- اقرأ إرشادات المساهمة .
- اقرأ مدونة قواعد السلوك .
- تأكد من توقيعك على اتفاقية ترخيص المساهم (CLA) .
- تحقق مما إذا كانت التغييرات التي أجريتها متوافقة مع الإرشادات .
- تحقق مما إذا كانت تغييراتك متوافقة مع أسلوب برمجة TensorFlow .
- قم بتشغيل اختبارات الوحدة .