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

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

Link to this section🤝 مدونة السلوك#

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

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

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

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

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

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

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

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

When adding new functions or classes, include Google-style docstrings for clear, standardized documentation. Always enclose both input and output types in parentheses (e.g., (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

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

All pull requests must pass the GitHub Actions Continuous Integration (CI) tests before they can be merged. These tests include linting, unit tests, and other checks to ensure that your changes meet the project's quality standards. Review the CI output and address any issues that arise.

Link to this section✨ أفضل الممارسات لمساهمات الكود#

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

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

Link to this section👀 مراجعة طلبات السحب#

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

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

Link to this section🐞 الإبلاغ عن الأخطاء#

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

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

Link to this section📜 الترخيص#

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

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

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

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

Link to this sectionلماذا يهم الامتثال لـ AGPL-3.0#

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

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

Link to this sectionكيفية الامتثال لـ AGPL-3.0#

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

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

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

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

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

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

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

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.

Link to this sectionهيكل مستودع مثال#

راجع مستودع قالب 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.

Link to this sectionالخلاصة#

Thank you for your interest in contributing to Ultralytics open-source YOLO projects. Your participation is essential in shaping the future of our software and building a vibrant community of innovation and collaboration. Whether you're enhancing code, reporting bugs, or suggesting new features, your contributions are invaluable.

نحن متحمسون لرؤية أفكارك تتحول إلى واقع ونقدر التزامك بتطوير تكنولوجيا كشف الأشياء (object detection). معاً، دعونا نواصل النمو والابتكار في هذه الرحلة المثيرة مفتوحة المصدر.

Link to this sectionالأسئلة الشائعة#

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

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

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

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

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

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

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

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

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

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

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

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

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