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

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

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

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

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

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

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

1. فورك المستودع: ابدأ بتكوين شوكة لمستودع 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، ما عليك سوى إضافة تعليق في طلب العلاقات العامة الخاص بك ينص على:

I have read the CLA Document and I sign the CLA

✍️ سلاسل المستندات Google

عند إضافة دوال أو فئات جديدة، يُرجى تضمين Google-style -style docstrings. توفر هذه السلاسل الوثائقية وثائق واضحة وموحدة تساعد المطورين الآخرين على فهم شفرتك البرمجية والحفاظ عليها.

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

    Args:
        arg1 (int): The first argument.
        arg2 (int): The second argument, with a default value of 4.

    Returns:
        (bool): True if successful, False otherwise.

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

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

    Args:
        arg1: The first argument.
        arg2: The second argument, with a default value of 4.

    Returns:
        True if successful, False otherwise.

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

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

✅ اختبارات CI لإجراءات GitHub GitHub

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

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

عند المساهمة برمز في مشاريع Ultralytics ضع هذه الممارسات الفضلى في الاعتبار:

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

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

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

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

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

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

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

📜 الترخيص

تستخدم Ultralytics رخصة جنو أفيرو العمومية GNU Affero Public Public License v3.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-Style Docstrings.

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

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

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

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

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

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

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

التعليقات