.. _contributing: ============ المساهمة ============ .. currentmodule:: sklearn هذا المشروع هو جهد جماعي، والجميع مرحب بهم للمساهمة. هو مستضاف على https://github.com/scikit-learn/scikit-learn. تم تحديد عملية صنع القرار وهيكل إدارة scikit-learn في :ref:`governance`. scikit-learn :ref:`انتقائي إلى حد ما ` عندما يتعلق الأمر بإضافة خوارزميات جديدة، وأفضل طريقة للمساهمة ومساعدة المشروع هي البدء في العمل على المشكلات المعروفة. انظر :ref:`new_contributors` للبدء. .. topic:: **مجتمعنا، قيمنا** نحن مجتمع قائم على الانفتاح والمناقشات الودية والتعليمية. نتطلع إلى معاملة الجميع على قدم المساواة، ونقدّر مساهماتهم. نحن نبحث بشكل خاص عن أشخاص من خلفيات غير ممثلة في برامج المصادر المفتوحة و scikit-learn على وجه الخصوص للمشاركة و المساهمة بخبراتهم وتجاربهم. يتم اتخاذ القرارات بناءً على الجدارة الفنية والتوافق في الآراء. الشفرة ليست هي الطريقة الوحيدة لمساعدة المشروع. مراجعة طلبات السحب، والإجابة على الأسئلة لمساعدة الآخرين في قوائم البريد أو المشكلات، وتنظيم وتدريس الدروس، والعمل على الموقع الإلكتروني، وتحسين الوثائق، كلها مساهمات لا تقدر بثمن. نحن نلتزم بمبادئ الانفتاح والاحترام ومراعاة الآخرين في مؤسسة Python Software Foundation: https://www.python.org/psf/codeofconduct/ في حالة مواجهة مشكلات أثناء استخدام هذه الحزمة، فلا تتردد في إرسال تذكرة إلى `متتبع مشكلات GitHub `_. نرحب أيضًا بنشر طلبات الميزات أو طلبات السحب. طرق المساهمة ================== هناك العديد من الطرق للمساهمة في scikit-learn، وأكثرها شيوعًا هي المساهمة بالشفرة أو الوثائق في المشروع. تحسين الوثائق لا يقل أهمية عن تحسين المكتبة نفسها. إذا وجدت خطأً مطبعيًا في الوثائق، أو قمت بإجراء تحسينات، فلا تتردد في إرسال بريد إلكتروني إلى قائمة البريد أو يفضل إرسال طلب سحب على GitHub. يمكن العثور على الوثائق الكاملة ضمن دليل doc/. ولكن هناك العديد من الطرق الأخرى للمساعدة. على وجه الخصوص، المساعدة في :ref:`تحسين وتنظيم والتحقيق في المشكلات ` و :ref:`مراجعة طلبات السحب الخاصة بالمطورين الآخرين ` هي مساهمات قيّمة للغاية تقلل العبء على مسؤولي المشروع. هناك طريقة أخرى للمساهمة وهي الإبلاغ عن المشكلات التي تواجهها، وإعطاء "إعجاب" للمشكلات التي أبلغ عنها الآخرون والتي تهمك. يساعدنا أيضًا إذا نشرت الخبر: ارجع إلى المشروع من مدونتك ومقالاتك، واربطه من موقعك الإلكتروني، أو ببساطة ضع نجمة لتقول "أنا أستخدمه": .. raw:: html

في حالة ما إذا كانت المساهمة/المشكلة تتضمن تغييرات على مبادئ API أو تغييرات على التبعيات أو الإصدارات المدعومة، فيجب دعمها بواسطة :ref:`slep`، حيث يجب إرسال SLEP كطلب سحب إلى `مقترحات التحسين `_ باستخدام `قالب SLEP `_ ويتبع عملية صنع القرار الموضحة في :ref:`governance`. .. dropdown:: المساهمة في المشاريع ذات الصلة يزدهر Scikit-learn في نظام بيئي للعديد من المشاريع ذات الصلة، والتي قد يكون لديها أيضًا مشكلات ذات صلة للعمل عليها، بما في ذلك المشاريع الأصغر مثل: * `scikit-learn-contrib `__ * `joblib `__ * `sphinx-gallery `__ * `numpydoc `__ * `liac-arff `__ والمشاريع الأكبر: * `numpy `__ * `scipy `__ * `matplotlib `__ * وهكذا. ابحث عن المشكلات التي تحمل علامة "help wanted" أو ما شابه. قد تساعد مساعدة هذه المشاريع scikit-learn أيضًا. انظر أيضًا :ref:`related_projects`. سياسة المساهمات الآلية ============================== يرجى الامتناع عن إرسال مشكلات أو طلبات سحب تم إنشاؤها بواسطة أدوات آلية بالكامل. يحتفظ المسؤولون بالحق، وفقًا لتقديرهم الخاص، في إغلاق هذه الطلبات وحظر أي حساب مسؤول عنها. من الناحية المثالية، يجب أن تتبع المساهمات مناقشة بين البشر في شكل مشكلة. إرسال تقرير خطأ أو طلب ميزة ============================================ نحن نستخدم مشكلات GitHub لتتبع جميع الأخطاء وطلبات الميزات؛ لا تتردد في فتح مشكلة إذا وجدت خطأً أو ترغب في رؤية ميزة تم تنفيذها. في حالة مواجهة مشكلات أثناء استخدام هذه الحزمة، فلا تتردد في إرسال تذكرة إلى `متتبع الأخطاء `_. نرحب أيضًا بنشر طلبات الميزات أو طلبات السحب. يوصى بالتحقق من أن مشكلتك تتوافق مع القواعد التالية قبل الإرسال: - تحقق من أن مشكلتك لا يتم تناولها حاليًا بواسطة مشكلات `أخرى `_ أو `طلبات سحب أخرى `_. - إذا كنت ترسل طلب خوارزمية أو ميزة، فيرجى التحقق من أن الخوارزمية تفي بـ `متطلبات الخوارزمية الجديدة الخاصة بنا `_. - إذا كنت ترسل تقرير خطأ، فإننا نشجعك بشدة على اتباع الإرشادات الواردة في :ref:`filing_bugs`. .. _filing_bugs: كيفية كتابة تقرير خطأ جيد ----------------------------- عند إرسال مشكلة إلى `GitHub `__، يرجى بذل قصارى جهدك لـ اتباع هذه الإرشادات! سيؤدي ذلك إلى تسهيل تقديم ملاحظات جيدة لك: - يحتوي تقرير الخطأ المثالي على :ref:`مقتطف شفرة قصير قابل للتكرار `، وبهذه الطريقة يمكن لأي شخص محاولة إعادة إنتاج الخطأ بسهولة. إذا كان المقتطف الخاص بك أطول من حوالي 50 سطرًا، فيرجى ربطه بـ `Gist `_ أو مستودع GitHub. - إذا لم يكن من الممكن تضمين مقتطف قابل للتكرار، فيرجى تحديد ما هي **المقدرات و/أو الدوال المعنية وشكل البيانات**. - في حالة حدوث استثناء، يرجى **تقديم التتبع الكامل**. - يرجى تضمين **نوع نظام التشغيل ورقم الإصدار** الخاص بك، بالإضافة إلى **إصدارات Python و scikit-learn و numpy و scipy** الخاصة بك. يمكن العثور على هذه المعلومات عن طريق تشغيل: .. prompt:: bash python -c "import sklearn; sklearn.show_versions()" - يرجى التأكد من **تنسيق جميع مقتطفات التعليمات البرمجية ورسائل الخطأ في كتل التعليمات البرمجية المناسبة**. انظر `إنشاء كتل التعليمات البرمجية وتمييزها `_ لمزيد من التفاصيل. إذا كنت ترغب في المساعدة في تنظيم المشكلات، فاقرأ عن :ref:`bug_triaging`. المساهمة بالشفرة ================= .. note:: لتجنب ازدواجية العمل، يُنصح بشدة بالبحث في `متتبع المشكلات `_ و `قائمة طلبات السحب `_. إذا كنت تشك في ازدواجية العمل، أو إذا كنت ترغب في العمل على ميزة غير تافهة، فمن المستحسن فتح مشكلة أولاً في `متتبع المشكلات `_ للحصول على بعض الملاحظات من المطورين الأساسيين. هناك طريقة سهلة للعثور على مشكلة للعمل عليها وهي تطبيق تسمية "help wanted" في بحثك. يسرد هذا جميع المشكلات التي لم تتم المطالبة بها حتى الآن. للمطالبة بمشكلة لنفسك، يرجى التعليق تمامًا ``/take`` عليها حتى يقوم CI بتعيين المشكلة لك تلقائيًا. للحفاظ على جودة قاعدة التعليمات البرمجية وتسهيل عملية المراجعة، يجب أن تتوافق أي مساهمة مع :ref:`إرشادات الترميز ` الخاصة بالمشروع، على وجه الخصوص: - لا تقم بتعديل أسطر غير ذات صلة للحفاظ على تركيز طلب السحب على النطاق المذكور في وصفه أو مشكلته. - اكتب فقط تعليقات مضمنة تضيف قيمة وتجنب ذكر ما هو واضح: اشرح "السبب" بدلاً من "ماذا". - **الأهم من ذلك**: لا تساهم بالشفرة التي لا تفهمها. مصادر الفيديو --------------- هذه مقاطع فيديو تمهيدية خطوة بخطوة حول كيفية المساهمة في scikit-learn، وهي رفيق رائع لإرشادات النص التالية. يرجى التأكد من مراجعة إرشاداتنا أدناه، لأنها تصف أحدث سير عمل محدث لدينا. - دورة مكثفة في المساهمة في مشاريع Scikit-Learn والمصادر المفتوحة: `فيديو `__، `نسخة `__ - مثال على إرسال طلب سحب إلى scikit-learn: `فيديو `__، `نسخة `__ - إرشادات ونصائح عملية خاصة بالسباقات السريعة: `فيديو `__، `نسخة `__ - 3 مكونات لمراجعة طلب السحب: `فيديو `__، `نسخة `__ .. note:: في يناير 2021، تم تغيير اسم الفرع الافتراضي من ``master`` إلى ``main`` لمستودع scikit-learn GitHub لاستخدام مصطلحات أكثر شمولاً. تم إنشاء مقاطع الفيديو هذه قبل إعادة تسمية الفرع. بالنسبة للمساهمين الذين يشاهدون مقاطع الفيديو هذه لإعداد بيئة العمل الخاصة بهم وإرسال طلب سحب، يجب استبدال ``master`` بـ ``main``. كيفية المساهمة ----------------- الطريقة المفضلة للمساهمة في scikit-learn هي إنشاء شوكة `للمستودع الرئيسي `__ على GitHub، ثم إرسال "طلب سحب" (PR). في الخطوات القليلة الأولى، نشرح كيفية تثبيت scikit-learn محليًا، و كيفية إعداد مستودع git الخاص بك: 1. `أنشئ حسابًا `_ على GitHub إذا لم يكن لديك حساب بالفعل. 2. أنشئ شوكة `لمستودع المشروع `__: انقر فوق الزر "Fork" بالقرب من أعلى الصفحة. يؤدي هذا إلى إنشاء نسخة من الشفرة ضمن حسابك على حساب مستخدم GitHub. لمزيد من التفاصيل حول كيفية إنشاء شوكة لمستودع، انظر `هذا الدليل `_. 3. استنسخ شوكة مستودع scikit-learn من حساب GitHub الخاص بك إلى القرص المحلي الخاص بك: .. prompt:: bash git clone git@github.com:YourLogin/scikit-learn.git # add --depth 1 if your connection is slow cd scikit-learn 4. اتبع الخطوات من 2 إلى 6 في :ref:`install_bleeding_edge` لبناء scikit-learn في وضع التطوير والعودة إلى هذه الوثيقة. 5. قم بتثبيت تبعيات التطوير: .. prompt:: bash pip install pytest pytest-cov ruff mypy numpydoc black==24.3.0 .. _upstream: 6. أضف جهاز التحكم عن بُعد ``upstream``. يحفظ هذا مرجعًا إلى مستودع scikit-learn الرئيسي، والذي يمكنك استخدامه للحفاظ على مستودعك متزامنًا مع أحدث التغييرات: .. prompt:: bash git remote add upstream git@github.com:scikit-learn/scikit-learn.git 7. تحقق من تكوين أسماء مستعارة لجهاز التحكم عن بُعد `upstream` و `origin` بشكل صحيح عن طريق تشغيل `git remote -v` الذي يجب أن يعرض: .. code-block:: text 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 الخاص بك مكوّن بشكل صحيح. قد يكون من المفيد تشغيل بعض الاختبارات للتحقق من التثبيت الخاص بك. يرجى الرجوع إلى :ref:`pytest_tips` للحصول على أمثلة. تصف الخطوات التالية الآن عملية تعديل الشفرة وإرسال طلب سحب: 8. قم بمزامنة فرع ``main`` الخاص بك مع فرع ``upstream/main``، لمزيد من التفاصيل حول `وثائق GitHub `_: .. prompt:: bash git checkout main git fetch upstream git merge upstream/main 9. أنشئ فرع ميزة للاحتفاظ بتغييرات التطوير الخاصة بك: .. prompt:: bash git checkout -b my_feature وابدأ في إجراء تغييرات. استخدم دائمًا فرع ميزة. إنها ممارسة جيدة ألا تعمل أبدًا على فرع ``main``! 10. (**اختياري**) قم بتثبيت `pre-commit `_ لـ تشغيل عمليات فحص نمط الشفرة قبل كل إيداع: .. prompt:: bash pip install pre-commit pre-commit install يمكن تعطيل عمليات فحص pre-commit لإيداع معين باستخدام `git commit -n`. 11. قم بتطوير الميزة على فرع الميزة الخاص بك على جهاز الكمبيوتر الخاص بك، باستخدام Git لـ التحكم في الإصدار. عند الانتهاء من التحرير، أضف الملفات التي تم تغييرها باستخدام ``git add`` ثم ``git commit``: .. prompt:: bash git add modified_files git commit لتسجيل تغييراتك في Git، ثم ادفع التغييرات إلى حساب GitHub الخاص بك باستخدام: .. prompt:: bash git push -u origin my_feature 12. اتبع `هذه `_ التعليمات لإنشاء طلب سحب من شوكة الخاص بك. سيؤدي هذا إلى إرسال بريد إلكتروني إلى المودعين. قد ترغب في التفكير في إرسال بريد إلكتروني إلى قائمة البريد لمزيد من الرؤية. من المفيد غالبًا الحفاظ على مزامنة فرع الميزة المحلي الخاص بك مع أحدث التغييرات في مستودع scikit-learn الرئيسي: .. prompt:: bash git fetch upstream git merge upstream/main بعد ذلك، قد تحتاج إلى حل التعارضات. يمكنك الرجوع إلى `وثائق Git المتعلقة بحل تعارض الدمج باستخدام سطر الأوامر `_. .. topic:: تعلم Git `وثائق Git `_ و http://try.github.io هي موارد ممتازة للبدء في استخدام git، وفهم جميع الأوامر المعروضة هنا. .. _pr_checklist: قائمة التحقق من طلب السحب ---------------------- قبل دمج طلب سحب، يجب الموافقة عليه من قبل اثنين من المطورين الأساسيين. يجب وضع علامة على المساهمة غير المكتملة - حيث تتوقع القيام بمزيد من العمل قبل تلقي مراجعة كاملة - كـ `طلب سحب مسودة `__ وتغييره إلى "جاهز للمراجعة" عندما ينضج. قد تكون مسودات طلبات السحب مفيدة لـ: الإشارة إلى أنك تعمل على شيء ما لتجنب ازدواجية العمل، أو طلب مراجعة واسعة للوظائف أو API، أو البحث عن متعاونين. غالبًا ما تستفيد مسودات طلبات السحب من تضمين `قائمة مهام `_ في وصف طلب السحب. لتسهيل عملية المراجعة، نوصي بأن تتوافق مساهمتك مع القواعد التالية قبل وضع علامة على طلب السحب على أنه "جاهز للمراجعة". **ذات الخط العريض** مهمة بشكل خاص: 1. **امنح طلب السحب الخاص بك عنوانًا مفيدًا** يلخص ما تفعله مساهمتك. سيصبح هذا العنوان غالبًا رسالة الإيداع بمجرد دمجه، لذا يجب أن يلخص مساهمتك للأجيال القادمة. في بعض الحالات، يكفي "Fix ". "Fix #" ليس عنوانًا جيدًا أبدًا. 2. **تأكد من اجتياز التعليمات البرمجية الخاصة بك للاختبارات**. يمكن تشغيل مجموعة الاختبارات بأكملها باستخدام `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` لاختبار الوحدة :mod:`~sklearn.linear_model` بأكملها - `pytest doc/modules/linear_model.rst` للتأكد من صحة أمثلة دليل المستخدم. - `pytest sklearn/tests/test_common.py -k LogisticRegression` لتشغيل جميع عمليات فحص المقدرات لدينا (على وجه التحديد لـ `LogisticRegression`، إذا كان هذا هو المقدر الذي قمت بتغييره). قد تكون هناك اختبارات أخرى فاشلة، ولكن سيتم اكتشافها بواسطة CI لذا لست بحاجة إلى تشغيل مجموعة الاختبارات بأكملها محليًا. للحصول على إرشادات حول كيفية استخدام ``pytest`` بكفاءة، انظر :ref:`pytest_tips`. 3. **تأكد من أن التعليمات البرمجية الخاصة بك تحتوي على تعليقات ووثائق بشكل صحيح**، و **تأكد من عرض الوثائق بشكل صحيح**. لبناء الوثائق، يرجى الرجوع إلى إرشادات :ref:`contribute_documentation` الخاصة بنا. سيقوم CI أيضًا ببناء الوثائق: يرجى الرجوع إلى :ref:`generated_doc_CI`. 4. **الاختبارات ضرورية لقبول التحسينات**. يجب توفير إصلاحات الأخطاء أو الميزات الجديدة مع `اختبارات عدم الانحدار `_. تتحقق هذه الاختبارات من السلوك الصحيح للإصلاح أو الميزة. بهذه الطريقة، يتم منح تعديلات أخرى على قاعدة التعليمات البرمجية لتتوافق مع السلوك المطلوب. في حالة إصلاحات الأخطاء، في وقت طلب السحب، يجب أن تفشل اختبارات عدم الانحدار لقاعدة التعليمات البرمجية في فرع ``main`` وتنجح لشفرة طلب السحب. 5. اتبع :ref:`coding-guidelines`. 6. عند الاقتضاء، استخدم أدوات التحقق من الصحة والبرامج النصية في الوحدة :mod:`sklearn.utils`. يمكن العثور على قائمة بإجراءات الخدمة المتاحة للمطورين في صفحة :ref:`developers-utils`. 7. غالبًا ما تحل طلبات السحب مشكلة واحدة أو أكثر (أو طلبات سحب). إذا كان دمج طلب السحب الخاص بك يعني أنه يجب إغلاق بعض المشكلات/طلبات السحب الأخرى، فيجب عليك `استخدام الكلمات الرئيسية لإنشاء رابط لها `_ (على سبيل المثال، ``Fixes #1234``؛ يُسمح بمشكلات/طلبات سحب متعددة طالما أن كل واحدة مسبوقة بكلمة رئيسية). عند الدمج، سيتم إغلاق تلك المشكلات/طلبات السحب تلقائيًا بواسطة GitHub. إذا كان طلب السحب الخاص بك مرتبطًا ببساطة ببعض المشكلات/طلبات السحب الأخرى، أو كان يحل جزئيًا فقط المشكلة المستهدفة، فقم بإنشاء رابط لها دون استخدام الكلمات الرئيسية (على سبيل المثال، ``Towards #1234``). 8. يجب أن تدعم طلبات السحب غالبًا التغيير، من خلال معايير الأداء والكفاءة (انظر :ref:`monitoring_performances`) أو من خلال أمثلة الاستخدام. توضح الأمثلة أيضًا ميزات المكتبة وتعقيداتها للمستخدمين. ألقِ نظرة على أمثلة أخرى في الدليل `examples/ `_ كمرجع. يجب أن توضح الأمثلة سبب فائدة الوظيفة الجديدة في الممارسة العملية، وإذا أمكن، قارنها بالطرق الأخرى المتاحة في scikit-learn. 9. الميزات الجديدة لها بعض النفقات العامة للصيانة. نتوقع من مؤلفي طلبات السحب المشاركة في صيانة الشفرة التي يقدمونها، على الأقل في البداية. يجب توضيح الميزات الجديدة بوثائق سردية في دليل المستخدم، مع مقتطفات شفرة صغيرة. إذا كان ذلك مناسبًا، فيرجى أيضًا إضافة مراجع في الأدبيات، مع روابط PDF عندما يكون ذلك ممكنًا. 10. يجب أن يتضمن دليل المستخدم أيضًا الوقت المتوقع وتعقيد المساحة للخوارزمية وقابلية التوسع، على سبيل المثال "يمكن لهذه الخوارزمية التوسع إلى عدد كبير من العينات > 100000، ولكنها لا تتسع في الأبعاد: من المتوقع أن يكون `n_features` أقل من 100". يمكنك أيضًا مراجعة :ref:`code_review` الخاص بنا للحصول على فكرة عما سيتوقعه المراجعون. يمكنك التحقق من أخطاء البرمجة الشائعة باستخدام الأدوات التالية: * الشفرة ذات تغطية اختبار وحدة جيدة (على الأقل 80٪، أفضل 100٪)، تحقق باستخدام: .. prompt:: bash pip install pytest pytest-cov pytest --cov sklearn path/to/tests انظر أيضًا :ref:`testing_coverage`. * قم بتشغيل التحليل الثابت باستخدام `mypy`: .. prompt:: bash mypy sklearn يجب ألا ينتج عن هذا أخطاء جديدة في طلب السحب الخاص بك. يمكن أن يكون استخدام التعليق التوضيحي `# type: ignore` حلًا مؤقتًا لبعض الحالات التي لا يدعمها mypy، على وجه الخصوص، - عند استيراد وحدات C أو Cython، - على الخصائص ذات المُزَيِّنات. نقاط إضافية للمساهمات التي تتضمن تحليل أداء مع برنامج نصي مرجعي ومخرجات التنميط (انظر :ref:`monitoring_performances`). راجع أيضًا دليل :ref:`performance-howto` لمزيد من التفاصيل حول تحسين Cython والتنميط. .. note:: الحالة الحالية لقاعدة شفرة scikit-learn غير متوافقة مع جميع هذه الإرشادات، لكننا نتوقع أن يؤدي فرض هذه القيود على جميع المساهمات الجديدة إلى تحسين جودة قاعدة الشفرة الإجمالية في الاتجاه الصحيح. .. seealso:: للحصول على دليلين موثقين جيدًا ومفصّلين حول سير عمل التطوير، يرجى زيارة `Scipy Development Workflow `_ - و `Astropy Workflow for Developers `_ أقسام. التكامل المستمر (CI) --------------------------- * يتم استخدام خطوط أنابيب Azure لاختبار scikit-learn على Linux و Mac و Windows، مع تبعيات وإعدادات مختلفة. * يتم استخدام CircleCI لبناء المستندات للعرض. * يتم استخدام إجراءات Github لمهام مختلفة، بما في ذلك إنشاء عجلات وتوزيعات المصدر. * يتم استخدام Cirrus CI للبناء على ARM. .. _commit_markers: علامات رسالة الإيداع ^^^^^^^^^^^^^^^^^^^^^^ يرجى ملاحظة أنه إذا ظهرت إحدى العلامات التالية في رسالة الإيداع الأخيرة، فسيتم اتخاذ الإجراءات التالية. ====================== =================== علامة رسالة الإيداع الإجراء الذي يتخذه CI ====================== =================== [ci skip] يتم تخطي CI تمامًا [cd build] يتم تشغيل CD (يتم بناء العجلات وتوزيع المصدر) [cd build gh] يتم تشغيل CD فقط لإجراءات GitHub [cd build cirrus] يتم تشغيل CD فقط لـ Cirrus CI [lint skip] يتخطى خط أنابيب Azure التحقق من النسق [scipy-dev] البناء والاختبار باستخدام تصميمات التطوير الخاصة بالتبعيات لدينا (numpy و scipy وما إلى ذلك) [free-threaded] البناء والاختبار باستخدام CPython 3.13 free-threaded [pyodide] البناء والاختبار باستخدام Pyodide [azure parallel] تشغيل وظائف Azure CI بالتوازي [cirrus arm] تشغيل اختبار Cirrus CI ARM [float32] تشغيل اختبارات float32 عن طريق تعيين `SKLEARN_RUN_FLOAT32_TESTS=1`. انظر :ref:`environment_variable` لمزيد من التفاصيل [doc skip] لا يتم بناء المستندات [doc quick] يتم بناء المستندات، ولكن باستثناء مخططات معرض الأمثلة [doc build] يتم بناء المستندات بما في ذلك مخططات معرض الأمثلة (طويلة جدًا) ====================== =================== لاحظ أنه، افتراضيًا، يتم بناء الوثائق ولكن يتم تنفيذ الأمثلة التي يتم تعديلها مباشرةً بواسطة طلب السحب فقط. ملفات التأمين ^^^^^^^^^^ يستخدم CI ملفات التأمين لبناء بيئات بإصدارات محددة من التبعيات. عندما يحتاج طلب سحب إلى تعديل التبعيات أو إصداراتها، يجب تحديث ملفات التأمين وفقًا لذلك. يمكن القيام بذلك عن طريق التعليق في طلب السحب: .. code-block:: text @scikit-learn-bot update lock-files سيقوم بوت بدفع إيداع إلى فرع طلب السحب الخاص بك مع ملفات التأمين المحدثة في غضون بضع دقائق. تأكد من تحديد خانة الاختيار *السماح بالتعديلات من المسؤولين* الموجودة أسفل الشريط الجانبي الأيمن لطلب السحب. يمكنك أيضًا تحديد الخيارات `--select-build` و `--skip-build` و `--select-tag` كما هو الحال في سطر الأوامر. استخدم `--help` في البرنامج النصي `build_tools/update_environments_and_lock_files.py` لمزيد من المعلومات. فمثلا، .. code-block:: text @scikit-learn-bot update lock-files --select-tag main-ci --skip-build doc سيضيف البوت تلقائيًا :ref:`علامات رسالة الإيداع ` إلى الإيداع لعلامات معينة. إذا كنت ترغب في إضافة المزيد من العلامات يدويًا، فيمكنك القيام بذلك باستخدام الخيار `--commit-marker`. على سبيل المثال، سيؤدي التعليق التالي إلى تشغيل البوت لـ تحديث ملفات التأمين المتعلقة بالوثائق وإضافة علامة `[doc build]` إلى الإيداع: .. code-block:: text @scikit-learn-bot update lock-files --select-build doc --commit-marker "[doc build]" .. _stalled_pull_request: طلبات السحب المتوقفة --------------------- نظرًا لأن المساهمة في ميزة ما قد تكون عملية طويلة، تظهر بعض طلبات السحب غير نشطة ولكنها غير مكتملة. في مثل هذه الحالة، فإن توليها هو خدمة رائعة للمشروع. الآداب الجيدة لتولي المسؤولية هي: * **تحديد ما إذا كان طلب السحب متوقفًا** * قد يحتوي طلب السحب على تسمية "stalled" أو "help wanted" إذا كنا قد حددناه بالفعل كمرشح للمساهمين الآخرين. * لتحديد ما إذا كان طلب السحب غير النشط متوقفًا، اسأل المساهم عما إذا كان يخطط لمواصلة العمل على طلب السحب في المستقبل القريب. يشير عدم الرد في غضون أسبوعين بنشاط يدفع طلب السحب إلى الأمام إلى أن طلب السحب متوقف وسيؤدي إلى وضع علامة على طلب السحب هذا باسم "help wanted". لاحظ أنه إذا تلقى طلب السحب تعليقات سابقة على المساهمة التي لم تتلق ردًا في غضون شهر، فمن الآمن افتراض أن طلب السحب متوقف وتقصير وقت الانتظار إلى يوم واحد. بعد سباق سريع، سيتم توصيل متابعة طلبات السحب غير المدمجة التي تم فتحها أثناء السباق السريع إلى المشاركين في السباق السريع، وسيتم وضع علامة على طلبات السحب هذه باسم "sprint". يمكن إعادة تعيين طلبات السحب التي تحمل علامة "sprint" أو إعلان توقفها بواسطة قادة السباق السريع. * **تولّي طلب سحب متوقف**: لتولّي طلب سحب، من المهم التعليق على طلب السحب المتوقف الذي تتولاه والربط من طلب السحب الجديد بالطلب القديم. يجب إنشاء طلب السحب الجديد عن طريق السحب من الطلب القديم. المشكلات المتوقفة وغير المطالب بها ---------------------------- بشكل عام، ستحمل المشكلات الجاهزة للاستيلاء عليها علامة `"help wanted" `_. . ومع ذلك، لن تحمل جميع المشكلات التي تحتاج إلى مساهمين هذه العلامة، حيث أن علامة "help wanted" ليست محدثة دائمًا مع حالة المشكلة. يمكن للمساهمين العثور على المشكلات التي لا تزال جاهزة للاستيلاء عليها باستخدام الإرشادات التالية: * أولاً، لـ **تحديد ما إذا تم المطالبة بمشكلة ما**: * تحقق من طلبات السحب المرتبطة * تحقق من المحادثة لمعرفة ما إذا كان أي شخص قد قال إنه يعمل على إنشاء طلب سحب * إذا علّق مساهم على مشكلة ليقول إنه يعمل عليها، فسيتم توقع طلب سحب في غضون أسبوعين (مساهم جديد) أو 4 أسابيع (مساهم أو مطور أساسي)، ما لم يتم تحديد إطار زمني أكبر صراحةً. بعد ذلك الوقت، يمكن لمساهم آخر أن يأخذ المشكلة ويقدم طلب سحب لها. نشجع المساهمين على التعليق مباشرةً على المشكلة المتوقفة أو غير المطالب بها لإعلام أعضاء المجتمع أنهم سيعملون عليها. * إذا كانت المشكلة مرتبطة بـ :ref:`طلب سحب متوقف `، فننصح المساهمين باتباع الإجراء الموضح في قسم :ref:`stalled_pull_request` بدلاً من العمل مباشرةً على المشكلة. .. _new_contributors: مشكلات للمساهمين الجدد --------------------------- يجب على المساهمين الجدد البحث عن العلامات التالية عند البحث عن مشكلات. نحن نوصي بشدة بأن يتعامل المساهمون الجدد مع المشكلات "السهلة" أولاً: يساعد هذا المساهم على التعرف على سير عمل المساهمة، وعلى المطورين الأساسيين التعرف على المساهم؛ بالإضافة إلى ذلك، غالبًا ما نقلل من مدى سهولة حل مشكلة ما! - **علامة Good first issue** طريقة رائعة للبدء في المساهمة في scikit-learn هي اختيار عنصر من قائمة `good first issues `_ في متتبع المشكلات. يسمح لك حل هذه المشكلات بالبدء في المساهمة في المشروع دون معرفة مسبقة كبيرة. إذا كنت قد ساهمت بالفعل في scikit-learn، فيجب عليك إلقاء نظرة على المشكلات السهلة بدلاً من ذلك. - **علامة Easy** إذا كنت قد ساهمت بالفعل في scikit-learn، فهناك طريقة رائعة أخرى للمساهمة في scikit-learn وهي اختيار عنصر من قائمة `المشكلات السهلة `_ في متتبع المشكلات. ستكون مساعدتك في هذا المجال موضع تقدير كبير من قبل المطورين الأكثر خبرة لأنها تساعد في توفير وقتهم للتركيز على المشكلات الأخرى. - **علامة Help wanted** غالبًا ما نستخدم علامة Help wanted لتمييز المشكلات بغض النظر عن الصعوبة. بالإضافة إلى ذلك، نستخدم علامة Help wanted لتمييز طلبات السحب التي تم التخلي عنها من قبل المساهم الأصلي ومتاحة لشخص ما لالتقاطها من حيث توقف المساهم الأصلي. يمكن العثور على قائمة المشكلات التي تحمل علامة Help wanted `هنا `_. لاحظ أنه لن تحمل جميع المشكلات التي تحتاج إلى مساهمين هذه العلامة. .. _contribute_documentation: الوثائق ============= يسعدنا قبول أي نوع من الوثائق: * **سلاسل وثائق الدوال/الأساليب/الفئات:** تُعرف أيضًا باسم "وثائق API"، تصف هذه ما يفعله الكائن وتفاصيل أي معلمات وسمات و أساليب. توجد سلاسل الوثائق جنبًا إلى جنب مع الشفرة في `sklearn/ `_، ويتم إنشاؤها وفقًا لـ `doc/api_reference.py `_. لـ إضافة أو تحديث أو إزالة أو إهمال واجهة برمجة تطبيقات عامة مدرجة في :ref:`api_ref`، هذا هو المكان الذي يجب أن تنظر إليه. * **دليل المستخدم:** يوفر هذا معلومات أكثر تفصيلاً حول الخوارزميات المُنفَّذة في scikit-learn وعادةً ما توجد في جذر `doc/ `_ الدليل و `doc/modules/ `_. * **أمثلة:** توفر هذه أمثلة شفرة كاملة قد توضح استخدام وحدات scikit-learn، أو مقارنة خوارزميات مختلفة أو مناقشة تفسيرها، وما إلى ذلك. توجد الأمثلة في `examples/ `_. * **وثائق reStructuredText الأخرى:** توفر هذه معلومات مفيدة أخرى متنوعة (على سبيل المثال، دليل :ref:`contributing`) وتوجد في `doc/ `_. .. dropdown:: إرشادات لكتابة سلاسل الوثائق * عند توثيق المعلمات والسمات، إليك قائمة ببعض الأمثلة جيدة التنسيق .. code-block:: text 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" في سلاسل الوثائق سطرًا واحدًا لكل مرجع، مع نقطتين و شرح، على سبيل المثال: .. code-block:: text See Also -------- SelectKBest : تحديد الميزات بناءً على أعلى k نقاط. SelectFpr : تحديد الميزات بناءً على اختبار معدل إيجابية خاطئة. * أضف مقتطفًا واحدًا أو اثنين من الشفرة في قسم "Example" لإظهار كيفية استخدامه. .. dropdown:: إرشادات لكتابة دليل المستخدم ووثائق reStructuredText الأخرى من المهم الحفاظ على حل وسط جيد بين التفاصيل الرياضية والخوارزمية، وإعطاء القارئ حدسًا حول ما تفعله الخوارزمية. * ابدأ بشرح موجز وموجز لما تفعله الخوارزمية/الشفرة على البيانات. * سلّط الضوء على فائدة الميزة وتطبيقها الموصى به. ضع في اعتبارك تضمين تعقيد الخوارزمية (:math:`O\left(g\left(n\right)\right)`) إذا كان متاحًا، حيث يمكن أن تكون "قواعد التجربة" تعتمد بشكل كبير على الجهاز. فقط إذا لم تكن هذه التعقيدات متاحة، فيمكن توفير قواعد التجربة بدلاً من ذلك. * قم بتضمين شكل ذي صلة (تم إنشاؤه من مثال) لتوفير حدس. * قم بتضمين مثال شفرة قصير واحد أو اثنين لشرح استخدام الميزة. * عرّف أي معادلات رياضية ضرورية، متبوعة بالمراجع. عن طريق تأجيل الجوانب الرياضية، تصبح الوثائق أكثر سهولة للمستخدمين المهتمين في المقام الأول بفهم الآثار العملية للميزة بدلاً من آلياتها الأساسية. * عند تحرير ملفات reStructuredText (``.rst``)، حاول الحفاظ على طول السطر أقل من 88 حرفًا عندما يكون ذلك ممكنًا (تشمل الاستثناءات الروابط والجداول). * في ملفات reStructuredText الخاصة بـ scikit-learn، سيتم عرض كل من علامات الاقتباس المفردة والمزدوجة المحيطة بالنص كحرفية مضمنة (غالبًا ما تستخدم للتعليمات البرمجية، على سبيل المثال، `list`). يرجع ذلك إلى تكوينات محددة قمنا بتعيينها. يجب استخدام علامات الاقتباس المفردة في الوقت الحاضر. * الكثير من المعلومات يجعل من الصعب على المستخدمين الوصول إلى المحتوى الذي يهتمون به. استخدم القوائم المنسدلة لعواملها باستخدام بناء الجملة التالي .. code-block:: rst .. dropdown:: عنوان القائمة المنسدلة محتوى القائمة المنسدلة. ستؤدي المقتطف أعلاه إلى القائمة المنسدلة التالية: .. dropdown:: عنوان القائمة المنسدلة محتوى القائمة المنسدلة. * المعلومات التي يمكن إخفاؤها افتراضيًا باستخدام القوائم المنسدلة هي: * أقسام التسلسل الهرمي المنخفض مثل `References` و `Properties` وما إلى ذلك (انظر على سبيل المثال الأقسام الفرعية في :ref:`det_curve`)؛ * التفاصيل الرياضية المتعمقة؛ * السرد الخاص بحالة الاستخدام؛ * بشكل عام، السرد الذي قد يثير اهتمام المستخدمين الذين يرغبون في تجاوز جوانب عملية استخدام أداة معينة. * لا تستخدم القوائم المنسدلة لقسم `Examples` منخفض المستوى، حيث يجب أن يظل مرئيًا لجميع المستخدمين. تأكد من أن قسم `Examples` يأتي مباشرة بعد المناقشة الرئيسية مع أقل عدد ممكن من الأقسام المطوية بينهما. * اعلم أن القوائم المنسدلة تكسر المراجع المتقاطعة. إذا كان ذلك منطقيًا، فقم بإخفاء المرجع مع النص الذي يذكره. وإلا، فلا تستخدم القائمة المنسدلة. .. dropdown:: إرشادات لكتابة المراجع * عندما تتوفر مراجع ببليوغرافية بأرقام تعريف `arxiv `_ أو `معرف الكائن الرقمي `_، استخدم توجيهات sphinx `:arxiv:` أو `:doi:`. على سبيل المثال، انظر المراجع في :ref:`Spectral Clustering Graphs `. * بالنسبة لقسم "References" في سلاسل الوثائق، انظر :func:`sklearn.metrics.silhouette_score` كمثال.