إنتقل إلى المحتوى الرئيسي

🧪 دليل فرع التطوير

هل تريد تجربة أحدث الميزات قبل إصدارها رسميًا؟ يحتوي فرع dev على تحسينات متقدمة وميزات تجريبية ستصل في النهاية إلى الإصدار الرئيسي.

برنامج تجريبي

فرع dev تجريبي وقد يحتوي أخطاء أو ميزات غير مكتملة أو تغييرات كاسرة. استخدمه فقط إذا كنت مرتاحًا لاحتمال عدم الاستقرار وتريد المساعدة في تحسين Libre WebUI.

🎯 ما فرع dev؟​

فرع التطوير (dev) هو المكان الذي تُختبر فيه الميزات الجديدة قبل دمجها في فرع main المستقر. ويشمل:

  • أحدث الميزات غير الموجودة بعد في الإصدارات المستقرة
  • إصلاحات أخطاء قيد الاختبار
  • تحسينات تجريبية للواجهة والوظائف
  • تحسينات أداء قيد التطوير

🚀 استخدام فرع dev​

إعداد Docker (موصى به)​

تربط ملفات Compose الخاصة بالتطوير مقبس Docker للمضيف، ولذلك تعمل Work افتراضيًا عند توفر Docker. تعمل حاويات المهام على daemon المضيف وتظهر في docker ps. على Linux، اضبط DOCKER_GID في .env أولًا.

مع Ollama خارجي:

# Clone the repository
git clone https://github.com/libre-webui/libre-webui.git
cd libre-webui

# Switch to dev branch
git checkout dev

# Start the dev image with external Ollama
docker compose -f docker-compose.dev.external-ollama.yml up -d

Docker بسيط:

# Use the dev branch image
docker run -d -p 3000:3001 -v libre-webui:/app/backend/data --name libre-webui-dev --restart always ghcr.io/libre-webui/libre-webui:dev

من المصدر​

# Clone and switch to dev branch
git clone https://github.com/libre-webui/libre-webui.git
cd libre-webui
git checkout dev

# Install dependencies
npm install

# Start development server
npm run dev

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

ويواصل Chat إعادة الاتصال بعد انقطاعات الخادم الخلفي العابرة، بمهل لا تتجاوز 30 ثانية. وتعيد عملية اتصال ناجحة ضبط المهلة؛ ويلغي تسجيل الخروج المحاولات المعلقة. أما إخفاقات المصادقة فتوقف إعادة الاتصال التلقائية.

اختبار Work​

  1. شغّل Docker وتأكد من نجاح docker info للمستخدم نفسه الذي يشغّل الخادم الخلفي.
  2. شغّل Libre WebUI من المصدر باستخدام npm run dev.
  3. سجّل الدخول كمسؤول.
  4. اختر Work واستخدم نموذج Ollama أو Ollama Cloud أو نموذجًا مدعومًا بمكوّن إضافي مضبوط وقادرًا على الأدوات.

شغّل اختبارات موفّر الخادم الخلفي وسياسة الحاويات المركزة باستخدام:

npm run test:work

تتحقق الاختبارات من سياسة Docker المولّدة واحتواء المسارات وسلوك دورة الحياة والسعة ومهايئات الأدوات المتوافقة مع OpenAI وAnthropic وGemini. راجع Work: مساحات العمل المعزولة لمعرفة حدود بيئة التشغيل كاملةً.

🔄 البقاء على أحدث إصدار​

يُحدّث فرع dev كثيرًا. للحصول على أحدث التغييرات:

# Update your local dev branch
git pull origin dev

# Refresh the dev Compose stack
docker compose -f docker-compose.dev.external-ollama.yml pull
docker compose -f docker-compose.dev.external-ollama.yml up -d

# Or restart simple Docker
docker pull ghcr.io/libre-webui/libre-webui:dev
docker stop libre-webui-dev && docker rm libre-webui-dev
docker run -d -p 3000:3001 -v libre-webui:/app/backend/data --name libre-webui-dev --restart always ghcr.io/libre-webui/libre-webui:dev

🐛 هل وجدت خطأ؟ ساعدنا في التحسين!​

تقارير الأخطاء ذات قيمة كبيرة. إليك كيفية الإبلاغ بفعالية:

قبل الإبلاغ​

  1. تحقق من المشكلات الموجودة: ابحث في GitHub Issues لتجنب التكرار
  2. جرّب الإصدار المستقر: تأكد من أن الخطأ موجود في dev فقط (لا في فرع main)
  3. أعد إنتاجه باستمرار: هل تستطيع إحداث الخطأ مرة أخرى؟

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

🐛 أبلغ عن خطأ على GitHub

ضمّن المعلومات التالية:

**Environment:**

- Branch: dev
- Version: [git commit hash or date]
- OS: [Windows/macOS/Linux]
- Browser: [Chrome/Firefox/Safari version]
- Setup: [Docker/Source/etc.]
- Docker: [version and whether `docker info` succeeds, for Work issues]
- Work model/provider: [exact route, when applicable]

**Bug Description:**
Clear description of what went wrong

**Steps to Reproduce:**

1. Go to...
2. Click on...
3. See error...

**Expected Behavior:**
What should have happened

**Actual Behavior:**
What actually happened

**Screenshots/Logs:**
[If applicable, add screenshots or error logs]

**Work Activity:**
[Relevant tool call/result or preview output, with secrets removed]

الحصول على hash التزام Git​

# Find your current dev branch commit
git rev-parse HEAD

# Or get a short version
git rev-parse --short HEAD

🏆 المساهمة والتقدير​

يجعلك استخدام فرع dev جزءًا من مجتمع الاختبار لدينا. ويُقدَّر المساهمون بعدة طرق:

تقدير المساهمين​

  • الإدراج في CONTRIBUTORS.md
  • الذكر في ملاحظات الإصدار للمساهمات المهمة
  • نسبة التأليف المشترك في رسائل الالتزام
  • شكر خاص في إعلانات المشروع

المساهمون الحاليون​

يضم مجتمعنا الرائع:

هل تريد المساهمة بالشيفرة؟​

  1. أنشئ fork للمستودع
  2. أنشئ فرع ميزة من dev: git checkout -b feature/amazing-feature dev
  3. نفّذ تغييراتك
  4. أرسل Pull Request إلى فرع dev

راجع إرشادات المساهمة للتعليمات التفصيلية وميثاق المجتمع للمبادئ الأخلاقية للمشروع ونموذج الحوكمة.

فحوصات Pull Request​

يشغّل كل Pull Request، بما فيه Pull Request مكدّس إلى فرع وسيط لميزة أو إصلاح، سير العمل Format & Lint. تتحقق مهامه المستقلة من التنسيق وlint للواجهة الأمامية والخلفية وأنواع TypeScript واختبارات الحزم والانحدار وحزمة متصفح Playwright. يشغّل Chromium حزمة المتصفح كاملة، ويشغّل WebKit وFirefox أيضًا المسارات الحرجة للمصادقة والبث والنوافذ الحوارية وعلامات التبويب والأتمتة والتخزين وWork وتشغيل الكلام. يعمل كل محرك في مهمة CI خاصة به، وترفع عمليات التشغيل الفاشلة نتائج اختبار منفصلة.

تُثبَّت حزمة npm المختبرة في دليل مستهلك جديد على Linux وmacOS وWindows، باستخدام Node 22.22 وNode 24 كليهما. تثبّت هذه الفحوص تبعيات إنتاج حقيقية دون استعارة node_modules من نسخة المستودع، ثم تتحقق من بدء تشغيل CLI والجاهزية وتقديم الواجهة الأمامية وبقاء البيانات بعد إعادة التشغيل. شغّل الفحص نفسه محليًا بعد npm run build باستخدام npm run test:package-install، ومرّر حزمة tarball أو دليلًا يحتوي على حزمة tarball واحدة لاختبار عنصر بعينه. يحتاج التثبيت النظيف إلى الوصول إلى السجل وإلى متطلبات بناء الوحدات الأصلية المعتادة في المنصة عندما لا تتوفر تبعية مبنية مسبقًا.

تبني مهمة Work Computer منفصلة صورة الواجهة الرسومية من القاعدة المثبّتة لبيئة التشغيل، وتشغّل اختبار الانحدار الحقيقي للتفاعل. يجعل TEST_WORK_COMPUTER=1 غياب خدمة Docker أو الصورة سببًا لفشل الفحص بدل تخطيه. لإعادة إنتاج ذلك محليًا، اضبط هذه العلامة واضبط WORK_COMPUTER_TEST_IMAGE على صورة اختبار مبنية بشكل منفصل، ثم شغّل npm run test:work-computer. ومن دون الوضع الإلزامي، تظل عمليات التشغيل المحلية تبلّغ عن التخطي عندما تكون أداة الاختبار الرسومية الاختيارية غير موجودة.

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

يغطي CodeQL شيفرة JavaScript/TypeScript وPython وسير العمل في كل Pull Request. وتُصنَّف خوادم مزوّدي Python القابلة للتنفيذ ضمن examples/ صراحةً على أنها شيفرة في .gitattributes، لكي يشملها اكتشاف اللغات في GitHub. ويجب أن يتضمن إعداد Code Quality المُدار المنفصل كلًا من JavaScript/TypeScript وPython. إذا بقيت نتائج تاريخية بعد الإصلاح، فتحقق من المراجعة التي جرى تحليلها ومن تغطية اللغات، ثم حدّث التحليل المعني بعد نشر التغيير. لا ترفض النتائج الصحيحة، ولا تغيّر سلوكًا غير متزامن صحيحًا لمجرد تحسين التقييم المعروض.

كما يحزم سير العمل Electron Dev Build عناصر macOS وWindows وLinux. تحتفظ عمليات بناء macOS لـ Pull Request بتوقيع المشروع ad-hoc الخالي من بيانات الاعتماد، بحيث يمكن التحقق من التطبيق المحزّم قبل رفعه. ولا يحصل سير عمل Pull Request على بيانات اعتماد Developer ID أو التوثيق الرسمي.

يبني سير العمل Docker Build Test and Push صورتي amd64 وarm64 لكل Pull Request، بما في ذلك الطلبات المكدّسة إلى فروع وسيطة. لا تسجّل عمليات البناء الدخول إلى سجل حاويات، ولا تدفع digest للصور، ولا تنشر manifest متعدد البنى.

شغّل الفحوصات نفسها على مستوى التطبيق محليًا قبل فتح Pull Request:

npm run format:check
npm run lint
npm run test:package
npm run test:e2e

⚠️ ملاحظات مهمة​

سلامة البيانات​

  • انسخ بياناتك احتياطيًا قبل الانتقال إلى فرع dev
  • تعيش ملفات مهام Work في وحدات Docker مسماة منفصلة من النمط libre-work-*. انسخها احتياطيًا بمعزل عن دليل بيانات SQLite قبل اختبار تغييرات مدمرة في دورة حياة المهمة أو المستخدم.
  • استخدم وحدة Docker منفصلة لاختبار dev: 
    # Use different volume name for dev
    docker run -d -p 3000:3001 -v libre-webui-dev:/app/backend/data --name libre-webui-dev ghcr.io/libre-webui/libre-webui:dev

مشكلات محتملة​

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

متى تستخدم الإصدار المستقر​

عُد إلى فرع main المستقر إذا كنت:

  • تحتاج إلى الاعتمادية في أعمال مهمة
  • تواجه أخطاء كثيرة جدًا
  • تريد تجربة مستقرة ومختبرة
# Switch back to stable
git checkout main
docker compose -f docker-compose.external-ollama.yml pull
docker compose -f docker-compose.external-ollama.yml up -d

🌟 انضم إلى المجتمع​

هل أنت مستعد للمساعدة في تشكيل مستقبل Libre WebUI؟ 🚀

تحسّن اختباراتك وملاحظاتك ومساهماتك على فرع dev التجربة لكل المستخدمين مباشرةً. شكرًا لكونك جزءًا من مجتمع التطوير لدينا!