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

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

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

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

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

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

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

تثبيت بيئة التطوير#

استنسخ نسختك المتفرعة (أو المستودع الرئيسي) وثبّتها في وضع التحرير (-e) كي يشغّل Python ملفاتك المحلية ويعتمد كل تغيير دون الحاجة إلى إعادة التثبيت:

git clone https://github.com/YOUR_USERNAME/ultralytics.git
cd ultralytics
pip install -e .

لجعل مشروع آخر يعتمد على نسخة متفرعة بدلًا من حزمة PyPI، وجّه pip أو requirements.txt إلى فرع النسخة المتفرعة:

git+https://github.com/YOUR_USERNAME/ultralytics.git@my-custom-branch

تعديلات الوثائق#

يوجد مصدر الوثائق ضمن docs/en/. من جذر المستودع، ثبّت تبعيات التطوير وشغّل التحقق الصارم الكامل قبل فتح طلب سحب:

uv pip install -e ".[dev]"
python docs/build_docs.py

يُعدّ التحقق المراجع المُنشأة ووحدات الماكرو وصفحات المقارنة قبل تشغيل zensical build --strict. للحصول على معاينة مباشرة أسرع للصفحات التي لا تستخدم وحدات الماكرو، شغّل zensical serve.

توقيع اتفاقية CLA#

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

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

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

اختبارات CI عبر GitHub Actions#

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

أفضل الممارسات للمساهمة بالشيفرة#

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

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

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

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

• تحقق من اختبارات الوحدات: تأكد من أن طلب السحب يتضمن اختبارات للميزات أو التغييرات الجديدة.
• راجع تحديثات الوثائق: تأكد من تحديث الوثائق لتعكس التغييرات.
• قيّم أثر الأداء: فكّر في كيفية تأثير التغييرات على الأداء.
• تحقق من اختبارات 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.

الخلاصة#

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

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

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