المساهمة في مشاريع 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) الخاصة بنا. تضمن هذه الاتفاقية القانونية ترخيص مساهماتك على النحو السليم، مما يسمح بمواصلة توزيع المشروع بموجب ترخيص 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

اختبارات التكامل المستمر عبر إجراءات GitHub#

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

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

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

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

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

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

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

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

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

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

الترخيص#

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

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

جعل مشروع YOLO الخاص بك مفتوح المصدر بموجب ترخيص AGPL-3.0#

هل تستخدم نماذج YOLO أو شيفرة Ultralytics في مشروعك؟ يفرض ترخيص 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).
     • شيفرة الواجهة الخلفية والواجهة الأمامية إذا كانت جزءًا من تطبيق ويب.
     • أي [مكتبات تابعة لجهات خارجية](https://ultralytics-translation-0.invalid أجريت عليها تعديلات.
     • بيانات التدريب إذا كانت مطلوبة للتشغيل/إعادة التدريب وقابلة لإعادة التوزيع.

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

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

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