المساهمة#

هذا المشروع هو جهد جماعي، والجميع مرحب بهم للمساهمة. هو مستضاف على scikit-learn/scikit-learn. تم تحديد عملية صنع القرار وهيكل إدارة scikit-learn في حوكمة Scikit-learn وصنع القرار.

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

مجتمعنا، قيمنا

نحن مجتمع قائم على الانفتاح والمناقشات الودية والتعليمية.

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

يتم اتخاذ القرارات بناءً على الجدارة الفنية والتوافق في الآراء.

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

نحن نلتزم بمبادئ الانفتاح والاحترام ومراعاة الآخرين في مؤسسة Python Software Foundation: https://www.python.org/psf/codeofconduct/

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

طرق المساهمة#

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

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

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

في حالة ما إذا كانت المساهمة/المشكلة تتضمن تغييرات على مبادئ API أو تغييرات على التبعيات أو الإصدارات المدعومة، فيجب دعمها بواسطة مقترحات التحسين (SLEPs)، حيث يجب إرسال SLEP كطلب سحب إلى مقترحات التحسين باستخدام قالب SLEP ويتبع عملية صنع القرار الموضحة في حوكمة Scikit-learn وصنع القرار.

سياسة المساهمات الآلية#

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

من الناحية المثالية، يجب أن تتبع المساهمات مناقشة بين البشر في شكل مشكلة.

إرسال تقرير خطأ أو طلب ميزة#

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

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

يوصى بالتحقق من أن مشكلتك تتوافق مع القواعد التالية قبل الإرسال:

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

كيفية كتابة تقرير خطأ جيد#

عند إرسال مشكلة إلى GitHub، يرجى بذل قصارى جهدك لـ اتباع هذه الإرشادات! سيؤدي ذلك إلى تسهيل تقديم ملاحظات جيدة لك:

يحتوي تقرير الخطأ المثالي على مقتطف شفرة قصير قابل للتكرار، وبهذه الطريقة يمكن لأي شخص محاولة إعادة إنتاج الخطأ بسهولة. إذا كان المقتطف الخاص بك أطول من حوالي 50 سطرًا، فيرجى ربطه بـ Gist أو مستودع GitHub.
إذا لم يكن من الممكن تضمين مقتطف قابل للتكرار، فيرجى تحديد ما هي المقدرات و/أو الدوال المعنية وشكل البيانات.
في حالة حدوث استثناء، يرجى تقديم التتبع الكامل.
يرجى تضمين نوع نظام التشغيل ورقم الإصدار الخاص بك، بالإضافة إلى إصدارات Python و scikit-learn و numpy و scipy الخاصة بك. يمكن العثور على هذه المعلومات عن طريق تشغيل:
```
python -c "import sklearn; sklearn.show_versions()"
```
يرجى التأكد من تنسيق جميع مقتطفات التعليمات البرمجية ورسائل الخطأ في كتل التعليمات البرمجية المناسبة. انظر إنشاء كتل التعليمات البرمجية وتمييزها لمزيد من التفاصيل.

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

المساهمة بالشفرة#

ملاحظة

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

هناك طريقة سهلة للعثور على مشكلة للعمل عليها وهي تطبيق تسمية "help wanted" في بحثك. يسرد هذا جميع المشكلات التي لم تتم المطالبة بها حتى الآن. للمطالبة بمشكلة لنفسك، يرجى التعليق تمامًا /take عليها حتى يقوم CI بتعيين المشكلة لك تلقائيًا.

للحفاظ على جودة قاعدة التعليمات البرمجية وتسهيل عملية المراجعة، يجب أن تتوافق أي مساهمة مع إرشادات الترميز الخاصة بالمشروع، على وجه الخصوص:

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

مصادر الفيديو#

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

دورة مكثفة في المساهمة في مشاريع Scikit-Learn والمصادر المفتوحة: فيديو، نسخة
مثال على إرسال طلب سحب إلى scikit-learn: فيديو، نسخة
إرشادات ونصائح عملية خاصة بالسباقات السريعة: فيديو، نسخة
3 مكونات لمراجعة طلب السحب: فيديو، نسخة

ملاحظة

في يناير 2021، تم تغيير اسم الفرع الافتراضي من master إلى main لمستودع scikit-learn GitHub لاستخدام مصطلحات أكثر شمولاً. تم إنشاء مقاطع الفيديو هذه قبل إعادة تسمية الفرع. بالنسبة للمساهمين الذين يشاهدون مقاطع الفيديو هذه لإعداد بيئة العمل الخاصة بهم وإرسال طلب سحب، يجب استبدال master بـ main.

كيفية المساهمة#

الطريقة المفضلة للمساهمة في scikit-learn هي إنشاء شوكة للمستودع الرئيسي على GitHub، ثم إرسال "طلب سحب" (PR).

في الخطوات القليلة الأولى، نشرح كيفية تثبيت scikit-learn محليًا، و كيفية إعداد مستودع git الخاص بك:

أنشئ حسابًا على GitHub إذا لم يكن لديك حساب بالفعل.
أنشئ شوكة لمستودع المشروع: انقر فوق الزر "Fork" بالقرب من أعلى الصفحة. يؤدي هذا إلى إنشاء نسخة من الشفرة ضمن حسابك على حساب مستخدم GitHub. لمزيد من التفاصيل حول كيفية إنشاء شوكة لمستودع، انظر هذا الدليل.
استنسخ شوكة مستودع scikit-learn من حساب GitHub الخاص بك إلى القرص المحلي الخاص بك:
```
git clone git@github.com:YourLogin/scikit-learn.git  # add --depth 1 if your connection is slow
cd scikit-learn
```
اتبع الخطوات من 2 إلى 6 في البناء من المصدر لبناء scikit-learn في وضع التطوير والعودة إلى هذه الوثيقة.

قم بتثبيت تبعيات التطوير:

pip install pytest pytest-cov ruff mypy numpydoc black==24.3.0

أضف جهاز التحكم عن بُعد upstream. يحفظ هذا مرجعًا إلى مستودع scikit-learn الرئيسي، والذي يمكنك استخدامه للحفاظ على مستودعك متزامنًا مع أحدث التغييرات:
```
git remote add upstream git@github.com:scikit-learn/scikit-learn.git
```

تحقق من تكوين أسماء مستعارة لجهاز التحكم عن بُعد upstream و origin بشكل صحيح عن طريق تشغيل git remote -v الذي يجب أن يعرض:

origin  git@github.com:YourLogin/scikit-learn.git (fetch)
origin  git@github.com:YourLogin/scikit-learn.git (push)
upstream        git@github.com:scikit-learn/scikit-learn.git (fetch)
upstream        git@github.com:scikit-learn/scikit-learn.git (push)

يجب أن يكون لديك الآن تثبيت عامل لـ scikit-learn، ومستودع git الخاص بك مكوّن بشكل صحيح. قد يكون من المفيد تشغيل بعض الاختبارات للتحقق من التثبيت الخاص بك. يرجى الرجوع إلى أسماء مستعارة وأعلام pytest مفيدة للحصول على أمثلة.

تصف الخطوات التالية الآن عملية تعديل الشفرة وإرسال طلب سحب:

قم بمزامنة فرع main الخاص بك مع فرع upstream/main، لمزيد من التفاصيل حول وثائق GitHub:
```
git checkout main
git fetch upstream
git merge upstream/main
```
أنشئ فرع ميزة للاحتفاظ بتغييرات التطوير الخاصة بك:
```
git checkout -b my_feature
```
وابدأ في إجراء تغييرات. استخدم دائمًا فرع ميزة. إنها ممارسة جيدة ألا تعمل أبدًا على فرع main!
(اختياري) قم بتثبيت pre-commit لـ تشغيل عمليات فحص نمط الشفرة قبل كل إيداع:
```
pip install pre-commit
pre-commit install
```
يمكن تعطيل عمليات فحص pre-commit لإيداع معين باستخدام git commit -n.
قم بتطوير الميزة على فرع الميزة الخاص بك على جهاز الكمبيوتر الخاص بك، باستخدام Git لـ التحكم في الإصدار. عند الانتهاء من التحرير، أضف الملفات التي تم تغييرها باستخدام git add ثم git commit:
```
git add modified_files
git commit
```
لتسجيل تغييراتك في Git، ثم ادفع التغييرات إلى حساب GitHub الخاص بك باستخدام:
```
git push -u origin my_feature
```
اتبع هذه التعليمات لإنشاء طلب سحب من شوكة الخاص بك. سيؤدي هذا إلى إرسال بريد إلكتروني إلى المودعين. قد ترغب في التفكير في إرسال بريد إلكتروني إلى قائمة البريد لمزيد من الرؤية.

من المفيد غالبًا الحفاظ على مزامنة فرع الميزة المحلي الخاص بك مع أحدث التغييرات في مستودع scikit-learn الرئيسي:

git fetch upstream
git merge upstream/main

بعد ذلك، قد تحتاج إلى حل التعارضات. يمكنك الرجوع إلى وثائق Git المتعلقة بحل تعارض الدمج باستخدام سطر الأوامر.

قائمة التحقق من طلب السحب#

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

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

امنح طلب السحب الخاص بك عنوانًا مفيدًا يلخص ما تفعله مساهمتك. سيصبح هذا العنوان غالبًا رسالة الإيداع بمجرد دمجه، لذا يجب أن يلخص مساهمتك للأجيال القادمة. في بعض الحالات، يكفي "Fix <ISSUE TITLE>". "Fix #<ISSUE NUMBER>" ليس عنوانًا جيدًا أبدًا.
تأكد من اجتياز التعليمات البرمجية الخاصة بك للاختبارات. يمكن تشغيل مجموعة الاختبارات بأكملها باستخدام pytest، ولكن لا يوصى بذلك عادةً لأنه يستغرق وقتًا طويلاً. غالبًا ما يكفي تشغيل الاختبار المتعلق بتغييراتك فقط: على سبيل المثال، إذا قمت بتغيير شيء ما في sklearn/linear_model/_logistic.py، فإن تشغيل الأوامر التالية سيكون كافيًا عادةً:
- pytest sklearn/linear_model/_logistic.py للتأكد من صحة أمثلة doctest
- pytest sklearn/linear_model/tests/test_logistic.py لتشغيل الاختبارات الخاصة بالملف
- pytest sklearn/linear_model لاختبار الوحدة linear_model بأكملها
- pytest doc/modules/linear_model.rst للتأكد من صحة أمثلة دليل المستخدم.
- pytest sklearn/tests/test_common.py -k LogisticRegression لتشغيل جميع عمليات فحص المقدرات لدينا (على وجه التحديد لـ LogisticRegression، إذا كان هذا هو المقدر الذي قمت بتغييره).
قد تكون هناك اختبارات أخرى فاشلة، ولكن سيتم اكتشافها بواسطة CI لذا لست بحاجة إلى تشغيل مجموعة الاختبارات بأكملها محليًا. للحصول على إرشادات حول كيفية استخدام pytest بكفاءة، انظر أسماء مستعارة وأعلام pytest مفيدة.
تأكد من أن التعليمات البرمجية الخاصة بك تحتوي على تعليقات ووثائق بشكل صحيح، و تأكد من عرض الوثائق بشكل صحيح. لبناء الوثائق، يرجى الرجوع إلى إرشادات الوثائق الخاصة بنا. سيقوم CI أيضًا ببناء الوثائق: يرجى الرجوع إلى generated_doc_CI.
الاختبارات ضرورية لقبول التحسينات. يجب توفير إصلاحات الأخطاء أو الميزات الجديدة مع اختبارات عدم الانحدار. تتحقق هذه الاختبارات من السلوك الصحيح للإصلاح أو الميزة. بهذه الطريقة، يتم منح تعديلات أخرى على قاعدة التعليمات البرمجية لتتوافق مع السلوك المطلوب. في حالة إصلاحات الأخطاء، في وقت طلب السحب، يجب أن تفشل اختبارات عدم الانحدار لقاعدة التعليمات البرمجية في فرع main وتنجح لشفرة طلب السحب.
اتبع إرشادات الترميز.
عند الاقتضاء، استخدم أدوات التحقق من الصحة والبرامج النصية في الوحدة sklearn.utils. يمكن العثور على قائمة بإجراءات الخدمة المتاحة للمطورين في صفحة أدوات مساعدة للمطورين.
غالبًا ما تحل طلبات السحب مشكلة واحدة أو أكثر (أو طلبات سحب). إذا كان دمج طلب السحب الخاص بك يعني أنه يجب إغلاق بعض المشكلات/طلبات السحب الأخرى، فيجب عليك استخدام الكلمات الرئيسية لإنشاء رابط لها (على سبيل المثال، Fixes #1234؛ يُسمح بمشكلات/طلبات سحب متعددة طالما أن كل واحدة مسبوقة بكلمة رئيسية). عند الدمج، سيتم إغلاق تلك المشكلات/طلبات السحب تلقائيًا بواسطة GitHub. إذا كان طلب السحب الخاص بك مرتبطًا ببساطة ببعض المشكلات/طلبات السحب الأخرى، أو كان يحل جزئيًا فقط المشكلة المستهدفة، فقم بإنشاء رابط لها دون استخدام الكلمات الرئيسية (على سبيل المثال، Towards #1234).
يجب أن تدعم طلبات السحب غالبًا التغيير، من خلال معايير الأداء والكفاءة (انظر monitoring_performances) أو من خلال أمثلة الاستخدام. توضح الأمثلة أيضًا ميزات المكتبة وتعقيداتها للمستخدمين. ألقِ نظرة على أمثلة أخرى في الدليل examples/ كمرجع. يجب أن توضح الأمثلة سبب فائدة الوظيفة الجديدة في الممارسة العملية، وإذا أمكن، قارنها بالطرق الأخرى المتاحة في scikit-learn.
الميزات الجديدة لها بعض النفقات العامة للصيانة. نتوقع من مؤلفي طلبات السحب المشاركة في صيانة الشفرة التي يقدمونها، على الأقل في البداية. يجب توضيح الميزات الجديدة بوثائق سردية في دليل المستخدم، مع مقتطفات شفرة صغيرة. إذا كان ذلك مناسبًا، فيرجى أيضًا إضافة مراجع في الأدبيات، مع روابط PDF عندما يكون ذلك ممكنًا.
يجب أن يتضمن دليل المستخدم أيضًا الوقت المتوقع وتعقيد المساحة للخوارزمية وقابلية التوسع، على سبيل المثال "يمكن لهذه الخوارزمية التوسع إلى عدد كبير من العينات > 100000، ولكنها لا تتسع في الأبعاد: من المتوقع أن يكون n_features أقل من 100".

يمكنك أيضًا مراجعة code_review الخاص بنا للحصول على فكرة عما سيتوقعه المراجعون.

يمكنك التحقق من أخطاء البرمجة الشائعة باستخدام الأدوات التالية:

الشفرة ذات تغطية اختبار وحدة جيدة (على الأقل 80٪، أفضل 100٪)، تحقق باستخدام:
```
pip install pytest pytest-cov
pytest --cov sklearn path/to/tests
```
انظر أيضًا testing_coverage.
قم بتشغيل التحليل الثابت باستخدام mypy:
```
mypy sklearn
```
يجب ألا ينتج عن هذا أخطاء جديدة في طلب السحب الخاص بك. يمكن أن يكون استخدام التعليق التوضيحي # type: ignore حلًا مؤقتًا لبعض الحالات التي لا يدعمها mypy، على وجه الخصوص،
- عند استيراد وحدات C أو Cython،
- على الخصائص ذات المُزَيِّنات.

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

ملاحظة

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

شاهد أيضا

للحصول على دليلين موثقين جيدًا ومفصّلين حول سير عمل التطوير، يرجى زيارة Scipy Development Workflow - و Astropy Workflow for Developers أقسام.

التكامل المستمر (CI)#

يتم استخدام خطوط أنابيب Azure لاختبار scikit-learn على Linux و Mac و Windows، مع تبعيات وإعدادات مختلفة.
يتم استخدام CircleCI لبناء المستندات للعرض.
يتم استخدام إجراءات Github لمهام مختلفة، بما في ذلك إنشاء عجلات وتوزيعات المصدر.
يتم استخدام Cirrus CI للبناء على ARM.

علامات رسالة الإيداع#

يرجى ملاحظة أنه إذا ظهرت إحدى العلامات التالية في رسالة الإيداع الأخيرة، فسيتم اتخاذ الإجراءات التالية.

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

ملفات التأمين#

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

@scikit-learn-bot update lock-files

سيقوم بوت بدفع إيداع إلى فرع طلب السحب الخاص بك مع ملفات التأمين المحدثة في غضون بضع دقائق. تأكد من تحديد خانة الاختيار السماح بالتعديلات من المسؤولين الموجودة أسفل الشريط الجانبي الأيمن لطلب السحب. يمكنك أيضًا تحديد الخيارات --select-build و --skip-build و --select-tag كما هو الحال في سطر الأوامر. استخدم --help في البرنامج النصي build_tools/update_environments_and_lock_files.py لمزيد من المعلومات. فمثلا،

@scikit-learn-bot update lock-files --select-tag main-ci --skip-build doc

سيضيف البوت تلقائيًا علامات رسالة الإيداع إلى الإيداع لعلامات معينة. إذا كنت ترغب في إضافة المزيد من العلامات يدويًا، فيمكنك القيام بذلك باستخدام الخيار --commit-marker. على سبيل المثال، سيؤدي التعليق التالي إلى تشغيل البوت لـ تحديث ملفات التأمين المتعلقة بالوثائق وإضافة علامة [doc build] إلى الإيداع:

@scikit-learn-bot update lock-files --select-build doc --commit-marker "[doc build]"

طلبات السحب المتوقفة#

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

تحديد ما إذا كان طلب السحب متوقفًا
- قد يحتوي طلب السحب على تسمية "stalled" أو "help wanted" إذا كنا قد حددناه بالفعل كمرشح للمساهمين الآخرين.
- لتحديد ما إذا كان طلب السحب غير النشط متوقفًا، اسأل المساهم عما إذا كان يخطط لمواصلة العمل على طلب السحب في المستقبل القريب. يشير عدم الرد في غضون أسبوعين بنشاط يدفع طلب السحب إلى الأمام إلى أن طلب السحب متوقف وسيؤدي إلى وضع علامة على طلب السحب هذا باسم "help wanted".
  
  لاحظ أنه إذا تلقى طلب السحب تعليقات سابقة على المساهمة التي لم تتلق ردًا في غضون شهر، فمن الآمن افتراض أن طلب السحب متوقف وتقصير وقت الانتظار إلى يوم واحد.
  
  بعد سباق سريع، سيتم توصيل متابعة طلبات السحب غير المدمجة التي تم فتحها أثناء السباق السريع إلى المشاركين في السباق السريع، وسيتم وضع علامة على طلبات السحب هذه باسم "sprint". يمكن إعادة تعيين طلبات السحب التي تحمل علامة "sprint" أو إعلان توقفها بواسطة قادة السباق السريع.
تولّي طلب سحب متوقف: لتولّي طلب سحب، من المهم التعليق على طلب السحب المتوقف الذي تتولاه والربط من طلب السحب الجديد بالطلب القديم. يجب إنشاء طلب السحب الجديد عن طريق السحب من الطلب القديم.

المشكلات المتوقفة وغير المطالب بها#

بشكل عام، ستحمل المشكلات الجاهزة للاستيلاء عليها علامة "help wanted". . ومع ذلك، لن تحمل جميع المشكلات التي تحتاج إلى مساهمين هذه العلامة، حيث أن علامة "help wanted" ليست محدثة دائمًا مع حالة المشكلة. يمكن للمساهمين العثور على المشكلات التي لا تزال جاهزة للاستيلاء عليها باستخدام الإرشادات التالية:

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

مشكلات للمساهمين الجدد#

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

علامة Good first issue

طريقة رائعة للبدء في المساهمة في scikit-learn هي اختيار عنصر من قائمة good first issues في متتبع المشكلات. يسمح لك حل هذه المشكلات بالبدء في المساهمة في المشروع دون معرفة مسبقة كبيرة. إذا كنت قد ساهمت بالفعل في scikit-learn، فيجب عليك إلقاء نظرة على المشكلات السهلة بدلاً من ذلك.
علامة Easy

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

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

الوثائق#

يسعدنا قبول أي نوع من الوثائق:

سلاسل وثائق الدوال/الأساليب/الفئات: تُعرف أيضًا باسم "وثائق API"، تصف هذه ما يفعله الكائن وتفاصيل أي معلمات وسمات و أساليب. توجد سلاسل الوثائق جنبًا إلى جنب مع الشفرة في sklearn/، ويتم إنشاؤها وفقًا لـ doc/api_reference.py. لـ إضافة أو تحديث أو إزالة أو إهمال واجهة برمجة تطبيقات عامة مدرجة في API Reference، هذا هو المكان الذي يجب أن تنظر إليه.
دليل المستخدم: يوفر هذا معلومات أكثر تفصيلاً حول الخوارزميات المُنفَّذة في scikit-learn وعادةً ما توجد في جذر doc/ الدليل و doc/modules/.
أمثلة: توفر هذه أمثلة شفرة كاملة قد توضح استخدام وحدات scikit-learn، أو مقارنة خوارزميات مختلفة أو مناقشة تفسيرها، وما إلى ذلك. توجد الأمثلة في examples/.
وثائق reStructuredText الأخرى: توفر هذه معلومات مفيدة أخرى متنوعة (على سبيل المثال، دليل المساهمة) وتوجد في doc/.

إرشادات لكتابة سلاسل الوثائق#

عند توثيق المعلمات والسمات، إليك قائمة ببعض الأمثلة جيدة التنسيق
```
n_clusters : int, default=3
    عدد المجموعات التي اكتشفتها الخوارزمية.

some_param : {"hello", "goodbye"}, bool or int, default=True
    يذهب وصف المعلمة هنا، والذي يمكن أن يكون إما سلسلة
    حرفية (إما `hello` أو `goodbye`)، أو منطقي، أو عدد صحيح. القيمة الافتراضية
    هي True.

array_parameter : {array-like, sparse matrix} of shape (n_samples, n_features) \
    or (n_samples,)
    تقبل هذه المعلمة البيانات بأي من الأشكال المذكورة، مع أحد
    الأشكال المذكورة. القيمة الافتراضية هي `np.ones(shape=(n_samples,))`.

list_param : list of int

typed_ndarray : ndarray of shape (n_samples,), dtype=np.int32

sample_weight : array-like of shape (n_samples,), default=None

multioutput_array : ndarray of shape (n_samples, n_classes) or list of such arrays
```
بشكل عام، ضع في اعتبارك ما يلي:
- استخدم الأنواع الأساسية في Python. (bool بدلاً من boolean)
- استخدم الأقواس لتعريف الأشكال: array-like of shape (n_samples,) أو array-like of shape (n_samples, n_features)
- بالنسبة للسلاسل ذات الخيارات المتعددة، استخدم الأقواس: input: {'log', 'squared', 'multinomial'}
- يمكن أن تكون البيانات أحادية البعد أو ثنائية الأبعاد مجموعة فرعية من {array-like, ndarray, sparse matrix, dataframe}. لاحظ أن array-like يمكن أن يكون أيضًا list، بينما ndarray هو numpy.ndarray فقط صراحةً.
- حدد dataframe عند استخدام ميزات "frame-like"، مثل أسماء الأعمدة.
- عند تحديد نوع بيانات القائمة، استخدم of كفاصل: list of int. عندما تدعم المعلمة مصفوفات تعطي تفاصيل حول الشكل و/أو نوع البيانات وقائمة من هذه المصفوفات، يمكنك استخدام أحد array-like of shape (n_samples,) or list of such arrays.
- عند تحديد dtype لـ ndarray، استخدم على سبيل المثال dtype=np.int32 بعد تعريف الشكل: ndarray of shape (n_samples,), dtype=np.int32. أنت يمكنك تحديد dtype متعددة كمجموعة: array-like of shape (n_samples,), dtype={np.float64, np.float32}. إذا أراد المرء ذكر دقة تعسفية، فاستخدم integral و floating بدلاً من Python dtype int و float. عندما يتم دعم كل من int و floating، فلا داعي لـ تحديد dtype.
- عندما تكون القيمة الافتراضية None، يلزم تحديد None فقط في النهاية باستخدام default=None. تأكد من تضمين في سلسلة الوثائق، ما يعنيه أن تكون المعلمة أو السمة None.
أضف "See Also" في سلاسل الوثائق للفئات/الدوال ذات الصلة.

يجب أن يكون "See Also" في سلاسل الوثائق سطرًا واحدًا لكل مرجع، مع نقطتين و شرح، على سبيل المثال:

See Also
--------
SelectKBest : تحديد الميزات بناءً على أعلى k نقاط.
SelectFpr : تحديد الميزات بناءً على اختبار معدل إيجابية خاطئة.

أضف مقتطفًا واحدًا أو اثنين من الشفرة في قسم "Example" لإظهار كيفية استخدامه.

إرشادات لكتابة دليل المستخدم ووثائق reStructuredText الأخرى#

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

ابدأ بشرح موجز وموجز لما تفعله الخوارزمية/الشفرة على البيانات.
سلّط الضوء على فائدة الميزة وتطبيقها الموصى به. ضع في اعتبارك تضمين تعقيد الخوارزمية (\(O\left(g\left(n\right)\right)\)) إذا كان متاحًا، حيث يمكن أن تكون "قواعد التجربة" تعتمد بشكل كبير على الجهاز. فقط إذا لم تكن هذه التعقيدات متاحة، فيمكن توفير قواعد التجربة بدلاً من ذلك.
قم بتضمين شكل ذي صلة (تم إنشاؤه من مثال) لتوفير حدس.
قم بتضمين مثال شفرة قصير واحد أو اثنين لشرح استخدام الميزة.
عرّف أي معادلات رياضية ضرورية، متبوعة بالمراجع. عن طريق تأجيل الجوانب الرياضية، تصبح الوثائق أكثر سهولة للمستخدمين المهتمين في المقام الأول بفهم الآثار العملية للميزة بدلاً من آلياتها الأساسية.
عند تحرير ملفات reStructuredText (.rst)، حاول الحفاظ على طول السطر أقل من 88 حرفًا عندما يكون ذلك ممكنًا (تشمل الاستثناءات الروابط والجداول).
في ملفات reStructuredText الخاصة بـ scikit-learn، سيتم عرض كل من علامات الاقتباس المفردة والمزدوجة المحيطة بالنص كحرفية مضمنة (غالبًا ما تستخدم للتعليمات البرمجية، على سبيل المثال، list). يرجع ذلك إلى تكوينات محددة قمنا بتعيينها. يجب استخدام علامات الاقتباس المفردة في الوقت الحاضر.
الكثير من المعلومات يجعل من الصعب على المستخدمين الوصول إلى المحتوى الذي يهتمون به. استخدم القوائم المنسدلة لعواملها باستخدام بناء الجملة التالي
```
.. dropdown:: عنوان القائمة المنسدلة

  محتوى القائمة المنسدلة.
```
ستؤدي المقتطف أعلاه إلى القائمة المنسدلة التالية:

عنوان القائمة المنسدلة#

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