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

Welcome! We're thrilled that you're considering contributing to our Ultralytics open-source projects. Your involvement not only helps enhance the quality of our repositories but also benefits the entire computer vision community. This guide provides clear guidelines and best practices to help you get started.

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

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

🚀 المساهمة عبر طلبات السحب (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. إنشاء طلب سحب: قدم طلب سحب من فرعك إلى الفرع main الخاص بمستودع Ultralytics الأصلي. قدم عنواناً واضحاً ووصفاً تفصيلياً يوضح الغرض من تغييراتك ونطاقها.

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

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

بعد تقديم طلب السحب الخاص بك، سيرشدك بوت CLA خلال عملية التوقيع. لتوقيع اتفاقية 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

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.

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

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

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

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

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

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

🐞 الإبلاغ عن الأخطاء (Bugs)

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

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

📜 الترخيص

تستخدم Ultralytics ترخيص GNU Affero العام الإصدار 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 الأصلي.
     • سكربتات التدريب والتحقق والاستدلال.
     • أوزان النموذج (Model weights) إذا تم تعديلها أو ضبطها بدقة.
     • ملفات التكوين (Configuration files)، وإعدادات البيئة (requirements.txt، Dockerfiles).
     • كود الواجهة الخلفية والأمامية إذا كان جزءاً من تطبيق ويب.
     • أي مكتبات تابعة لجهات خارجية قمت بتعديلها.
     • بيانات التدريب (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.

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

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

خاتمة

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). معاً، دعونا نستمر في النمو والابتكار في هذه الرحلة المثيرة مفتوحة المصدر.

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

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

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

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

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

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

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

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

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

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

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

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

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

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