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

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

شاهد: كيفية المساهمة في مستودع Ultralytics | نماذج Ultralytics ومجموعات البيانات والوثائق 🚀

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

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

🚀 المساهمة عبر طلبات السحب

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

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

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

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

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

I have read the CLA Document and I sign the CLA

✍️ سلاسل التوثيق بنمط 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

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

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

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

    Examples:
        >>> example_function(4, 4)  # True
    """
    equals = arg1 == arg2
    return equals

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

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

    Returns:
        equals (bool): True if arguments are equal, False otherwise.
        added (int): Sum of both input arguments.

    Examples:
        >>> equals, added = example_function(2, 2)  # True, 4
    """
    equals = arg1 == arg2
    added = arg1 + arg2
    return equals, added

Returns:
   (np.ndarray): Predicted masks with shape HxWxN.
   (list): Confidence scores for each instance.

Returns:
   (tuple): Tuple containing:
       - (np.ndarray): Predicted masks with shape HxWxN.
       - (list): Confidence scores for each instance.

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

    Args:
        arg1: The first argument.
        arg2: The second argument.

    Returns:
        True if arguments are equal, False otherwise.

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

def example_small_function(arg1: int, arg2: int = 4) -> bool:
    """Example function with a single-line docstring."""
    return arg1 == arg2

✅ اختبارات التكامل المستمر GitHub Actions

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

✨ أفضل الممارسات للمساهمات في التعليمات البرمجية

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

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

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

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

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

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

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

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

📜 الترخيص

تستخدم 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 يلزم مشروعك بشروطها.
• يعزز التعاون: يشجع على المشاركة والشفافية.

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

كيفية الامتثال لرخصة 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.

🎉 خاتمة

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

نحن متحمسون لرؤية أفكارك تنبض بالحياة ونقدر التزامك بتطوير تكنولوجيا الكشف عن الأجسام. معًا، دعنا نستمر في النمو والابتكار في هذه الرحلة المثيرة مفتوحة المصدر. ترميز سعيد! 🚀🌟

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

لماذا يجب عليّ المساهمة في مستودعات مفتوحة المصدر الخاصة بـ 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. تتضمن هذه الاختبارات التدقيق والاختبارات الوحدة وعمليات فحص أخرى للتأكد من أن التعليمات البرمجية تفي بمعايير جودة المشروع. راجع مخرجات CI وأصلح أي مشكلات. للحصول على معلومات مفصلة حول عملية CI ونصائح استكشاف الأخطاء وإصلاحها، راجع قسم اختبارات CI لـ GitHub Actions.

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

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

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

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

📅 تم إنشاؤه منذ سنة واحدة ✏️ تم التحديث منذ شهر واحد

تعليقات