المساهمة في مشاريع Ultralytics مفتوحة المصدر#

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

🤝 مدونة السلوك#

لضمان توفير بيئة ترحيبية وشاملة للجميع، يجب على جميع المساهمين الالتزام بـ مدونة السلوك الخاصة بنا. الاحترام، واللطف، والاحترافية هي جوهر مجتمعنا.

🚀 المساهمة عبر طلبات السحب (Pull Requests)#

نحن نقدر كثيراً المساهمات في شكل طلبات السحب (PRs). لجعل عملية المراجعة سلسة قدر الإمكان، يرجى اتباع الخطوات التالية:

1. نسخ المستودع (Fork): ابدأ بنسخ مستودع Ultralytics ذي الصلة (مثل ultralytics/ultralytics) إلى حسابك على GitHub.
2. إنشاء فرع (Branch): أنشئ فرعاً جديداً في المستودع المنسوخ الخاص بك مع إعطائه اسماً واضحاً ووصفياً يعكس تغييراتك (مثل fix-issue-123، add-feature-xyz).
3. قم بإجراء تغييراتك: نفذ تحسيناتك أو إصلاحاتك. تأكد من أن الكود الخاص بك يلتزم بإرشادات أسلوب البرمجة الخاصة بالمشروع وأنه لا يقدم أخطاء أو تحذيرات جديدة.
4. اختبر تغييراتك: قبل الإرسال، اختبار تغييراتك محلياً للتأكد من أنها تعمل كما هو متوقع ولا تتسبب في تراجعات. أضف اختبارات إذا كنت تقدم وظائف جديدة.
5. حفظ التغييرات (Commit): احفظ تغييراتك برسائل التزام موجزة ووصفية. إذا كانت تغييراتك تعالج مشكلة معينة، فقم تضمين رقم المشكلة (مثل Fix #123: Corrected calculation error.).
6. إنشاء طلب سحب (Pull Request): أرسل طلب سحب من فرعك إلى فرع main في مستودع Ultralytics الأصلي. قدم عنواناً واضحاً ووصفاً مفصلاً يوضح غرض ونطاق تغييراتك.

📝 توقيع اتفاقية ترخيص المساهم (CLA)#

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

بعد إرسال طلب السحب الخاص بك، سيرشدك بوت CLA خلال عملية التوقيع. لتوقيع CLA، ببساطة أضف تعليقاً في طلب السحب الخاص بك ينص على:

I have read the CLA Document and I sign the CLA

✍️ سلاسل التوثيق (Docstrings) بأسلوب Google#

عند إضافة وظائف أو فئات جديدة، قم تضمين مستندات نمط Google للحصول على توثيق واضح وموحد. احرص دائماً على إحاطة كل من المدخلات والمخرجات types بين قوسين (مثل (bool)، (np.ndarray)).

def example_function(arg1, arg2=4):
    """Example function demonstrating Google-style docstrings.

    Args:
        arg1 (int): The first argument.
        arg2 (int): The second argument.

    Returns:
        (bool): True if arguments are equal, False otherwise.

    Examples:
        >>> example_function(4, 4)  # True
        >>> example_function(1, 2)  # False
    """
    return arg1 == arg2

✅ اختبارات التكامل المستمر (CI) باستخدام GitHub Actions#

يجب أن تجتاز جميع طلبات السحب (pull requests) اختبارات GitHub Actions التكامل المستمر (CI) قبل أن يتم دمجها. تتضمن هذه الاختبارات التدقيق اللغوي (linting)، والاختبارات الوحدة، وفحوصات أخرى لضمان أن التغييرات التي أجريتها تلبي معايير جودة المشروع. راجع مخرجات الـ CI وقم بمعالجة أي مشكلات قد تطرأ.

✨ أفضل الممارسات لمساهمات الكود#

عند المساهمة بالكود في مشاريع Ultralytics، ضع في اعتبارك أفضل الممارسات التالية:

• تجنب تكرار الكود: أعد استخدام الكود الحالي قدر الإمكان وقلل من الوسائط غير الضرورية.
• قم بإجراء تغييرات أصغر ومركزة: ركز على تعديلات محددة بدلاً من التغييرات واسعة النطاق.
• بسط الكود عند الإمكان: ابحث عن فرص لتبسيط الكود أو إزالة الأجزاء غير الضرورية.
• ضع في اعتبارك التوافق: قبل إجراء التغييرات، ضع في اعتبارك ما إذا كانت قد تؤدي إلى كسر الكود الحالي الذي يستخدم Ultralytics.
• استخدم تنسيقاً متسقاً: يمكن لأدوات مثل Ruff Formatter أن تساعد في الحفاظ على الاتساق الأسلوبي.
• أضف اختبارات مناسبة: قم تضمين اختبارات للميزات الجديدة لضمان عملها كما هو متوقع.

👀 مراجعة طلبات السحب#

مراجعة طلبات السحب هي طريقة قيمة أخرى للمساهمة. عند مراجعة طلبات السحب:

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

🐞 الإبلاغ عن الأخطاء#

نحن نقدر بشدة تقارير الأخطاء لأنها تساعدنا في تحسين جودة وموثوقية مشاريعنا. عند الإبلاغ عن خطأ عبر مشكلات GitHub:

• تحقق من المشكلات الموجودة: ابحث أولاً لمعرفة ما إذا كان الخطأ قد تم الإبلاغ عنه بالفعل.
• قدم مثالاً قابلاً لإعادة الإنتاج بحد أدنى: أنشئ مقطع برمجياً صغيراً ومتكاملاً يعيد إنتاج المشكلة باستمرار. هذا أمر بالغ الأهمية لعملية التصحيح الفعالة.
• صف البيئة: حدد نظام التشغيل الخاص بك، وإصدار Python، وإصدارات المكتبات ذات الصلة (مثل torch، ultralytics)، والأجهزة (وحدة المعالجة المركزية (CPU)/وحدة معالجة الرسومات (GPU)).
• اشرح السلوك المتوقع مقابل الفعلي: اذكر بوضوح ما كنت تتوقع حدوثه وما حدث بالفعل. قم بتضمين أي رسائل خطأ أو سجلات تتبع (tracebacks).

📜 الترخيص#

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

نشجع جميع المساهمين على التعرف على شروط رخصة AGPL-3.0 للمساهمة بفعالية وأخلاقية في مجتمع Ultralytics مفتوح المصدر.

🌍 جعل مشروع YOLO الخاص بك مفتوح المصدر بموجب AGPL-3.0#

هل تستخدم نماذج أو شفرات Ultralytics YOLO في مشروعك؟ يتطلب رخصة AGPL-3.0 أن يكون عملك المشتق بأكمله مفتوح المصدر أيضاً بموجب ترخيص AGPL-3.0. يضمن هذا أن تظل التعديلات والمشاريع الكبيرة المبنية على أسس مفتوحة المصدر مفتوحة.

لماذا يهم الامتثال لـ AGPL-3.0#

• يحافظ على البرمجيات مفتوحة: يضمن أن التحسينات والأعمال المشتقة تفيد المجتمع.
• متطلب قانوني: استخدام كود مرخص بـ AGPL-3.0 يلزم مشروعك بشروطه.
• يعزز التعاون: يشجع على المشاركة والشفافية.

إذا كنت تفضل عدم جعل مشروعك مفتوح المصدر، ففكر في الحصول على ترخيص المؤسسات (Enterprise License).

كيفية الامتثال لـ AGPL-3.0#

الامتثال يعني جعل الكود المصدري الكامل المقابل لمشروعك متاحاً للجمهور بموجب ترخيص AGPL-3.0.

1. اختر نقطة البداية الخاصة بك:

   • انسخ مستودع Ultralytics YOLO: قم بنسخ مستودع Ultralytics YOLO مباشرة إذا كنت تبني عليه بشكل وثيق.
   • استخدم قالب Ultralytics: ابدأ باستخدام مستودع قالب Ultralytics للحصول على إعداد نظيف وحديث يدمج YOLO.

2. رخص مشروعك:

   • أضف ملف LICENSE يحتوي على النص الكامل لـ رخصة AGPL-3.0.
   • أضف ملاحظة في أعلى كل ملف مصدري تشير إلى الترخيص.

3. انشر الكود المصدري الخاص بك:

   • اجعل الكود المصدري لمشروعك بالكامل متاحاً للجمهور (على سبيل المثال، على GitHub). يتضمن ذلك:
     • التطبيق أو النظام الأكبر الكامل الذي يتضمن نموذج أو كود YOLO.
     • أي تعديلات تم إجراؤها على كود Ultralytics YOLO الأصلي.
     • سكربتات التدريب، والتحقق من الصحة، والاستنتاج.
     • أوزان النموذج إذا تم تعديلها أو ضبطها بدقة.
     • ملفات التكوين، وإعدادات البيئة (requirements.txt، Dockerfiles).
     • شيفرة الواجهة الخلفية والأمامية إذا كانت جزءاً من تطبيق ويب.
     • أي مكتبات تابعين لجهات خارجية قمت بتعديلها.
     • بيانات التدريب إذا كانت مطلوبة للتشغيل/إعادة التدريب وقابلة لإعادة التوزيع.

4. وثق بوضوح:

   • قم بتحديث README.md الخاص بك لبيان أن المشروع مرخص بموجب AGPL-3.0.
   • قم بتضمين تعليمات واضحة حول كيفية إعداد وبناء وتشغيل مشروعك من الكود المصدري.
   • انسب الفضل إلى Ultralytics YOLO بشكل مناسب، مع وضع رابط يعود إلى المستودع الأصلي. مثال:

     This project utilizes code from [Ultralytics YOLO](https://github.com/ultralytics/ultralytics), licensed under AGPL-3.0.

هيكل مستودع مثال#

ارجع إلى مستودع قالب Ultralytics للحصول على مثال عملي لهيكل المشروع:

my-yolo-project/
│
├── LICENSE               # Full AGPL-3.0 license text
├── README.md             # Project description, setup, usage, license info & attribution
├── pyproject.toml        # Dependencies (or requirements.txt)
├── scripts/              # Training/inference scripts
│   └── train.py
├── src/                  # Your project's source code
│   ├── __init__.py
│   ├── data_loader.py
│   └── model_wrapper.py  # Code interacting with YOLO
├── tests/                # Unit/integration tests
├── configs/              # YAML/JSON config files
├── docker/               # Dockerfiles, if used
│   └── Dockerfile
└── .github/              # GitHub specific files (e.g., workflows for CI)
    └── workflows/
        └── ci.yml

باتباع هذه الإرشادات، تضمن الامتثال لـ AGPL-3.0، ودعم النظام البيئي مفتوح المصدر الذي يتيح أدوات قوية مثل Ultralytics YOLO.

الخلاصة#

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

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

الأسئلة الشائعة#

لماذا يجب أن أساهم في مستودعات Ultralytics YOLO مفتوحة المصدر؟#

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

كيف يمكنني توقيع اتفاقية ترخيص المساهم (CLA) لـ Ultralytics YOLO؟#

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

I have read the CLA Document and I sign the CLA

لمزيد من المعلومات، راجع قسم توقيع CLA.

ما هي سلاسل التوثيق بأسلوب Google، ولماذا هي مطلوبة لمساهمات Ultralytics YOLO؟#

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

كيف يمكنني التأكد من اجتياز تغييراتي لاختبارات GitHub Actions CI؟#

قبل أن يتم دمج طلب السحب الخاص بك، يجب أن يجتاز جميع اختبارات التكامل المستمر (CI) لـ GitHub Actions. تتضمن هذه الاختبارات التدقيق اللغوي، واختبارات الوحدات، والفحوصات الأخرى لضمان توافق الشيفرة مع معايير الجودة للمشروع. راجع مخرجات التكامل المستمر وأصلح أي مشكلات. للحصول على معلومات مفصلة حول عملية التكامل المستمر ونصائح استكشاف الأخطاء وإصلاحها، راجع قسم اختبارات التكامل المستمر لـ GitHub Actions.

كيف أقوم بالإبلاغ عن خطأ في مستودعات Ultralytics YOLO؟#

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

ماذا تعني رخصة AGPL-3.0 إذا كنت أستخدم Ultralytics YOLO في مشروعي الخاص؟#

إذا كنت تستخدم شيفرة أو نماذج Ultralytics YOLO (المرخصة بموجب AGPL-3.0) في مشروعك، فإن ترخيص AGPL-3.0 يتطلب أن يكون مشروعك بأكمله (العمل المشتق) مرخصاً أيضاً بموجب AGPL-3.0 وأن توفر شيفرته المصدرية الكاملة للعامة. يضمن هذا الحفاظ على الطبيعة مفتوحة المصدر للبرمجيات طوال أعمالها المشتقة. إذا لم تتمكن من تلبية هذه المتطلبات، فعليك الحصول على ترخيص المؤسسات. راجع قسم جعل مشروعك مفتوح المصدر للحصول على التفاصيل.