# المساهمة في 🤗 Transformers

> [!WARNING]
> يواجه مستودع Transformers حاليًا ضغطًا كبيرًا بسبب العدد الهائل من طلبات الدمج وتعليقات المشكلات التي يكتبها وكلاء البرمجة. نحن نواجه حاليًا عنق زجاجة في قدرتنا على مراجعة هذه الطلبات والتعليقات والرد عليها. ونتيجةً لذلك، **نطلب من المساهمين الجدد عدم استخدام وكلاء البرمجة لإنشاء مشكلات أو طلبات دمج** في الوقت الحالي. كما نطلب من الوكلاء المستقلين عدم فتح أي طلبات دمج أو مشكلات في الوقت الراهن.
>
> من المرجح أن تُغلق طلبات الدمج التي يبدو أنها مكتوبة بواسطة وكيل دون مراجعة، وقد نقوم بحظر المستخدمين الذين يقومون بذلك بشكل متكرر أو بسوء نية.

 فلسفتنا في وكلاء الأكواد بالتفصيل

نحن ندرك أن وكلاء الأكواد أدوات قوية للغاية، ويستخدمها العديد من الأشخاص في Hugging Face في عملهم. ومع ذلك، من المهم إدراك أن **إذا كنت ببساطة تشغّل وكيل أكواد وتولّد طلب سحب (PR) لمشروع مفتوح المصدر، فأنت مجرد وسيط بين المراجعين والوكيل**. على الرغم من أن القيام بذلك يُنتج شيئاً يبدو مساهمة مفيدة للغاية، إلا أنه في الواقع لم يكن هناك سبب لاشتراكك؛ إذ كان بإمكان المراجعين ببساطة تشغيل وكيل الأكواد بأنفسهم.

إذا كنت ترغب في الإسهام بشكل مفيد في مجال البرمجيات مفتوحة المصدر في عصر الوكلاء، **فإن عليك القيام بأشياء لا يستطيع الوكلاء إنجازها بأنفسهم**. وبشكل خاص، وجدنا أن ما يلي مفيد للغاية:
- تشخيص دقيق للأخطاء. تميل وكلاء البرمجة إلى إصلاح المشكلات بسرعة عبر حلول مؤقتة غالباً ما تؤدي إلى تضخم الكود
أو عدم التوافق مع نماذج أخرى. إن قضاء الوقت في تحديد السبب الدقيق للمشكلة، وتحديدًا تحديد أول التزامن الذي ظهر فيه (على سبيل المثال باستخدام [git bisect](https://git-scm.com/docs/git-bisect)) أمرٌ ذو قيمة.
- قلّل حجم التغييرات. راجع طلب الإرسال الخاص بك للتخلّص من أي تغييرات غير ضرورية. تأكد من أنك لم تُرسل أي سكربتات اختبار
أو ملفات غير ذات صلة. أضِف التعليقات فقط إذا كانت ضرورية حقًا؛ فوكلاء البرمجة يميلون إلى إضافة ثلاث دوال جديدة وتعليقات متعددة الأسطر لجذب الانتباه إلى كل الجهد الذي بذلوه. إذا كان بإمكانك تقديم طلب دمج (PR) يكون إصلاحًا من سطر واحد، فاجعله كذلك. هذا يجعل مراجعة طلب الدمج أسهل بكثير ويزيد من فرص قبوله.
- خذ وقتك لإعادة إنتاج المشكلة. في كثير من الأحيان، عندما يبلغ المستخدم عن مشكلة، يكون السبب الفعلي للمشكلة
مشاكل في بيئة العمل على جهازهم، أو يخطئون في تشخيص المشكلة ويقترحون حلاً غير صالح. تثق وكلاء الأكواد كثيرًا بتعليقات المستخدم، مما يؤدي إلى حلول رديئة، أحيانًا لمشاكل غير موجودة! كتابة سكربت بسيط لإعادة إنتاج المشكلة وتشغيله للتأكد من رؤيتها أمرٌ قيّم.
- قارن مقابل نماذج أخرى. مستودع Transformers كبير جداً، وكثير من النماذج تقوم بأشياء مشابهة. عند
عند إصلاح خطأ برمجي، من المفيد التحقق مما إذا كان هذا الخطأ موجودًا في نماذج أخرى. إذا ذكر طلب المساهمة الخاص بك أنه «تم الإصلاح باستخدام النهج نفسه المعتمد في (نموذج آخر)»، مع تضمين رابط إلى الكود ذي الصلة، فإن ذلك يكون مفيدًا للغاية للمحافظين على المشروع، لأنه يخبرنا بأن الإصلاح على الأرجح صحيح ومتوافق مع بقية قاعدة الكود. غالبًا ما ينظر وكلاء الكود إلى الشيفرة «بشكل ضيق»، ويقومون بإصلاحات تؤدي إلى انحراف النماذج عن بقية قاعدة الكود.
- تجنّب تقديم طلبات دمج صغيرة أو "روتينية". في الماضي، كنّا نقبل هذه الطلبات، لكن بالنظر إلى العدد الهائل الحالي، لم نعد نقبلها ببساطة.
يكون لديك وقت لإجراء تعديلات صغيرة على الأسلوب أو تصحيح الأخطاء المطبعية في التعليقات. يمكنك تقديم قيمة تتجاوز ما يقدمه وكيل البرمجيات (Code Agent) ببساطة من خلال امتلاك ذوق جيد فيما يتعلق بما هو مهم حقاً. غالباً ما يركّز وكلاء البرمجيات على «الأخطاء النظرية» التي تُكتشف عبر تحليل الكود، والتي نادراً ما تسبب مشاكل في الممارسة العملية، إن لم تكن لا تسبب أي مشكلة على الإطلاق. وعادةً لا تستحق هذه الأخطاء الإصلاح ما لم يتمكن مهاجم من استغلالها.
- تحقّق من الاختبارات محليًا وفي CI. قبل فتح طلب دمج، شغّل `make fix-repo` واستخدم `utils/tests_fetcher.py` ل
شاهد قائمة الاختبارات التي تغطي الملفات التي قمت بتعديلها في فرع طلب الإرسال الخاص بك. شغّل هذه الاختبارات محلياً، وتأكد من نجاحها قبل فتح طلب الإرسال. بعد فتح طلب الإرسال، يرجى التحقق من أن CI أخضر (ناجح) وإصلاح أي مشاكل قبل طلب مراجعة من أي شخص! هذا يقلل من إزعاج الإشعارات بشكل كبير، مما يحافظ على راحة صانعي المحتوى.

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

إذا لم تكن متأكداً من أين تبدأ، فاطّلع على [المشكلات الجيدة للمبتدئين](https://github.com/huggingface/transformers/labels/Good%20First%20Issue) للحصول على مشكلات أسهل في التعامل معها. أما إذا كنت تبحث عن تحدٍّ أكبر، فتعرّف على [المشكلات الجيدة للمستوى الثاني](https://github.com/huggingface/transformers/labels/Good%20Second%20Issue). بغضّ النظر عن الطريقة التي تختارها للمساهمة، يرجى مراعاة [مدونة السلوك](https://github.com/huggingface/transformers/blob/main/CODE_OF_CONDUCT.md) الخاصة بنا والالتزام بها.

إذا استمتعتَ باستخدام Transformers، فلا تتردد في الإشارة إليه وإخبارنا بكيفية استخدامه، أو التحدث عنه على Twitter، أو منح المستودع نجمة!

استُلهم هذا الدليل بشكل كبير من [دليل scikit-learn للمساهمة](https://github.com/scikit-learn/scikit-learn/blob/main/CONTRIBUTING.md).

## المحتويات

1. [الإعداد](#set-up)
   - [Windows](#windows)
2. [فتح القضايا](#opening-issues)
   - [مشكلة تتعلق بخطأ برمجي](#bug-related-issue)
   - [طلب ميزة](#feature-request)
3. [إضافة نموذج جديد](#adding-a-new-model)
   - [جدول إضافة النماذج](#model-addition-timeline)
4. [التوثيق](#docs)
5. [المساهمات الوكيلية](#agentic-contributions)

## الإعداد

1. أنشئ نسخة خاصة بك من [Transformers](https://github.com/huggingface/transformers) عبر زر **Fork** على GitHub، ثم استنسخها محليًا.

  ```bash
  git clone git@github.com:<your Github handle>/transformers.git
  cd transformers
  ```

2. أضف مستودع Transformers كمصدر بعيد باسم `upstream`. يشير `origin` إلى نسختك المستنسخة بينما يشير `upstream` إلى المصدر الموثوق. يتيح لك ذلك مزامنة فرع `main` المحلي لديك قبل الدفع إلى `origin` وفتح طلب سحب.

  ```bash
  git remote add upstream https://github.com/huggingface/transformers.git
  git remote -v
  # origin    git@github.com:<your Github handle>/transformers.git (fetch)
  # origin    git@github.com:<your Github handle>/transformers.git (push)
  # upstream  https://github.com/huggingface/transformers.git (fetch)
  # upstream  https://github.com/huggingface/transformers.git (push)
  ```

3. حافظ على تحديث فرعك (fork) الخاص بك وابدأ فرعًا (branch) جديدًا للعمل عليه. يمكنك أيضًا مزامنة فرعك من واجهة GitHub باستخدام زر **Sync fork**.

  ```bash
  git checkout main && git pull upstream main && git push origin main
  git switch -c a-descriptive-name-for-my-branch
  ```

4. قم بتثبيت المكتبة في وضع قابل للتحرير. استخدم `[dev]` لمعظم المساهمات لأنه يتضمن أدوات التطوير اللازمة لفحوصات الأسلوب والجودة. استخدم `[torch,testing]` للمساهمات المتعلقة بالنماذج، أو `[quality]` للتغييرات التي تقتصر على التوثيق والإصلاحات الصغيرة عندما لا تكون هناك حاجة إلى مجموعة تبعيات التطوير الكاملة.

  ```bash
  pip install -e ".[dev]"

  # for model contributions
  pip install -e ".[torch,testing]"

  # for docs-only changes and small fixes
  pip install -e ".[quality]"
  ```

### Windows

على نظام Windows، ما لم تكن تستخدم [WSL](https://learn.microsoft.com/en-us/windows/wsl/)، فعليك ضبط git لتحويل نهايات الأسطر من `CRLF` إلى `LF`.

```bash
git config core.autocrlf input
```

طريقة واحدة لتشغيل أمر `make` على نظام Windows هي استخدام MSYS2.

1. [تنزيل MSYS2](https://www.msys2.org/) (نفترض أنه مثبّت في `C:\msys64`).
2. افتح سطر الأوامر `C:\msys64\msys2.exe` (يجب أن يكون متاحًا من قائمة **ابدأ**).
3. شغّل في الطرفية: `pacman -Syu` ثم ثبّت `make` باستخدام `pacman -S make`.
4. أضف `C:\msys64\usr\bin` إلى متغير البيئة PATH الخاص بك.

يمكنك الآن استخدام `make` من أي طرفية (PowerShell، cmd.exe، إلخ).

## فتح القضايا

استخدم [القوالب](https://github.com/huggingface/transformers/tree/main/.github/ISSUE_TEMPLATE) الخاصة بالمشكلات للمساعدة في البدء.

### مشكلة متعلقة بخطأ برمجي

تأكد من أن الخطأ لم يُبلَّغ عنه من قبل قبل فتح تذكرة (استخدم شريط البحث في GitHub تحت Issues). يجب أن تكون التذكرة متعلقة بخطأ في Transformers وليس في كودك الخاص.

إذا كنت غير متأكد مما إذا كان الخلل في كودك أو في المكتبة، فاطلب المساعدة أولاً في [المنتدى](https://discuss.huggingface.co/) أو على [Discord](https://discord.com/invite/hugging-face-879548962464493619). يساعد ذلك في إبقاء GitHub متركّزاً على مشكلات المكتبة التي يمكن اتخاذ إجراء بشأنها.

قم بتضمين ما يلي حتى نتمكن من حل المشكلة بسرعة.

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

للحصول على إصدارات نظام التشغيل والبرمجيات تلقائيًا، نفّذ الأمر التالي.

```bash
transformers env
```

### طلب ميزة

افتح مشكلة ووصف:

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

## إضافة نموذج جديد

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

اتبع الأدلة أدناه.

1. [إضافة نموذج باستخدام Transformers المعياري](https://github.com/huggingface/transformers/blob/main/docs/source/en/modular_transformers.md) — قم بتنفيذ النموذج باستخدام الملف المعياري وتوليد ملفات نمذجة مستقلة.
2. [توليد توثيق تلقائي](https://github.com/huggingface/transformers/blob/main/docs/source/en/auto_docstring.md) — استخدم مُزيِّن `@auto_docstring` لتوليد توثيق متسق دون الحاجة إلى أكواد مكررة.
3. [الاختبار](https://github.com/huggingface/transformers/blob/main/docs/source/en/testing.md) — اكتب ونفّذ اختبارات النموذج للتحقق من الصواب والحفاظ على قابلية المساهمة للصيانة. بالنسبة لنماذج اللغة السببية، ورّث من مُختبِر نموذج اللغة السببية حيثما أمكن. أعطِ الأولوية لاختبارات التكامل لأنها تتحقق من مسار المعالج الكامل، ومجزّئ النص، والنموذج مقابل نقاط التفتيش الفعلية.
4. [قواعد بنية النموذج](https://github.com/huggingface/transformers/blob/main/docs/source/en/modeling_rules.md) — تأكد من أن ملفاتك تجتاز قواعد بنية النموذج الثابتة التي يفرضها `make typing`.

تتطلب بعض إضافات النماذج عملاً إضافياً على مستوى التكامل.

- [أضف مكونات معالجة الرؤية](https://github.com/huggingface/transformers/blob/main/docs/source/en/add_vision_processing_components.md) إذا كان نموذجك يتطلب مدخلات صور أو فيديو.
- [تحميل الأوزان الديناميكي](https://github.com/huggingface/transformers/blob/main/docs/source/en/weightconverter.md) إذا لم تتطابق أسماء معاملات نقطة التفتيش المنشورة مع تطبيق Transformers.

### جدول زمني لإضافة النماذج

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

- التكامل من اليوم الأول: جعل النموذج متاحًا في Transformers في يوم الإصدار مع إصدار نسخة جديدة. نقدم المساعدة لدعم أهم الميزات الأساسية (مثل التكميم، وFlashAttention، وذاكرة KV، وغيرها)، ونراجع المسودات المبكرة، كما يمكننا تولي تنفيذ النموذج اعتمادًا على الجدول الزمني.

  أرسل بريدًا إلكترونيًا إلى transformers@huggingface.co قبل أسابيع قليلة، خاصةً في حال البنى المعمارية الجديدة. سنعمل معك على فرع خاص حتى يصبح نقطة التفتيش الخاصة بك والإصدار جاهزين.

- التكامل خلال الأسبوع نفسه: عادةً ما تُضاف النماذج ذات الطلب المرتفع خلال أسبوع واحد، حتى عندما لا يتواصل المؤلف.

  افتح مشكلة باستخدام [قالب النموذج الجديد](https://github.com/huggingface/transformers/issues/new?assignees=&labels=New+model&projects=&template=new-model-addition.yml) لتقديم طلب. المشكلات ذات النشاط الأعلى تتقدم في قائمة الانتظار بشكل أسرع.

- التكامل بعد الإصدار: تُضاف النماذج التي لا تحظى بطلب قوي، أو التي لا نملك سعة كافية للتعامل معها، بعد الإصدار في المنبع.

  المشكلات المفتوحة الموسومة بـ ["نموذج جديد"](https://github.com/huggingface/transformers/issues?q=is%3Aopen+is%3Aissue+label%3A%22New+model%22) هي نقطة الدخول للمساهمين الخارجيين. ابدأ بالهندسات الأكثر طلبًا لتعظيم الأثر. سنراجعها ونرشدك خلال العملية.

- إصدار يعتمد على Hub: انشر نموذجك مباشرةً على Hub عبر دعم [remote-code](https://github.com/huggingface/transformers/blob/main/docs/source/en/models.md#custom-models) في Transformers، دون الحاجة إلى طلب دمج (PR) في المستودع الأصلي.

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

## التوثيق

نرحّب دائمًا بأي تحسينات على التوثيق، مثل تصحيح الأخطاء الإملائية، أو إضافة محتوى مفقود، أو توضيح الشروح غير الواضحة. فيما يتعلق بمرجع الواجهة البرمجية (API) المولّد من ملفات المصدر، استخدم مُزيّن [`@auto_docstring`](https://github.com/huggingface/transformers/blob/main/docs/source/en/auto_docstring.md) عندما ينطبق. افتح طلب سحب (pull request) مباشرةً لإصلاحات التوثيق الجوهرية.

راجع وثائق [README](https://github.com/huggingface/transformers/blob/main/docs/README.md) لمزيد من التفاصيل حول كيفية تحرير الوثائق والنحو الذي نستخدمه.

## مساهمات الوكلاء

نرحّب بالمساهمات المدعومة بالذكاء الاصطناعي. يجب أن تكون منسّقة ومحدّدة النطاق ومُتحقَّقًا منها للحفاظ على قابلية حمل المراجعة.

- لا تُقدِّم طلبات دمج "وكيل خالص". يتحمّل مقدِّم الطلب البشري مسؤولية مراجعة جميع الأسطر المعدَّلة، والتحقق من السلوك من البداية إلى النهاية، وتشغيل الاختبارات ذات الصلة.
- إذا تم استخدام أدوات الذكاء الاصطناعي، فافصح عن ذلك في وصف طلب الإضافة (PR) وشمل: رابط التنسيق، والتمييز عن طلبات الإضافة الموجودة (إن كان ذلك منطبقاً)، وأوامر الاختبار/نتائجه.
- تجنّب طلبات الدمج "العابرة" التي لا تضيف قيمة (مثل تصحيح خطأ إملائي واحد، أو تنظيف نمطي معزول، أو إصلاح قيمة افتراضية قابلة للتغيير واحدة، إلخ). اجمع عمليات التنظيف الميكانيكية ضمن نطاق واضح ومنهجي.
- تنسيق المسائل قبل فتح طلب سحب، ومراجعة طلبات السحب المشابهة، والانتظار حتى الحصول على الموافقة.

> [!NOTE]
> تُوضَّح هذه المواضيع للوكلاء في `AGENTS.md` مع تعليمات حول كيفية تنفيذها بشكل مستقل.