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

مقدمة

قبل أن تتعمق في التطوير، نأمل أن تستوعب الأمور التالية:
  • يُطوَّر Overleaf رسميًا في مستودع داخلي، وتُنشر النسخة المجتمعية (Community Edition) في overleaf/overleaf. ويتولى روبوت نسخ (copybot) مزامنة الشيفرة بين المستودعين الداخلي والعام.
  • يُعد Ayaka-notes/overleaf-pro نسخة متفرعة (fork) من Overleaf المجتمعي، ونأمل أن يستمر هذا المشروع على المدى الطويل، لذا يُرجى اتباع القواعد قبل تقديم أي مساهمات.

قواعد الإيداع (Commit)

  • يُرجى عدم إجراء تعديلات واسعة على شيفرة Overleaf الحالية. ركّز أكبر قدر ممكن من الوظائف في المجلد services/web/modules. سيقلل هذا من عبء العمل علينا عند دمج الشيفرة وتحديثها لاحقًا.
  • البرمجة التلقائية بمساعدة الذكاء الاصطناعي (Vibe coding) طريقة سهلة فعلًا، لكنها قد تُحدث فوضى في مشروعنا بسهولة وتجعله غير قابل للصيانة لاحقًا، لذا يُرجى استخدامها بحذر.
  • أعد استخدام مفاتيح الترجمة الموجودة كلما أمكن ذلك. وإذا كان مفتاح جديد ضروريًا حقًا، فأضفه إلى services/web/locales/locales_patches/added/ لجميع اللغات دفعة واحدة، راجع تحديث ترجمات i18n.
  • تجنّب إضافة متغيرات بيئة جديدة ما لم يكن ذلك ضروريًا للغاية. وإن لزم الأمر، فاحرص على أن تكون متسقة قدر الإمكان مع تلك الموجودة في Overleaf toolkit أو في docs.overleaf.com.

قواعد الفروع

نستخدم الفروع التالية لتطوير overleaf-pro:
  • main: يُستخدم هذا الفرع فقط لمزامنة الشيفرة من المصدر الأصلي، لذا يُرجى عدم إيداع أي تغييرات خارجية فيه. في هذا الفرع، نضع بعض الوسوم مثل ce-v[X.x.x]، والتي تشير إلى أن هذا يقابل v[X.x.x] في النسخة المجتمعية الرسمية من Overleaf. ملاحظة: هذا الوسم غير قابل للتغيير!
  • server-pro: هذا الفرع هو الفرع الافتراضي للتطوير اليومي.
  • feat-X: يُستخدم هذا الفرع لتطوير ميزة محددة، مثل feat-gitea-sync.
  • release-vX.Y.Z: الفرع المخصص للإصدار، وسنجري فيه بعض الإصلاحات العاجلة (hot-fix) قبل الإصدار. تحصل الإصدارات التصحيحية أيضًا على فرع خاص بها، مثل release-v6.3.1. ويُوسم الـ commit المُصدَر بالوسم pro-vX.Y.Z على هذا الفرع.

قواعد الفروع في Overleaf Pro

GitHub Action

تتولى GitHub Action عمليات التكامل والنشر المستمرين (CI/CD) تلقائيًا. لا تحتاج إلى بناء الصور على جهازك: فكل صورة أدناه تُبنى عبر سير عمل (workflow)، ويمكن بناء الصور التي تدعم التشغيل اليدوي بنقرة واحدة.
  • صور التطوير تحتوي كل منها على خدمة مصغّرة واحدة (web، webpack، clsi، …) لمعماريتي linux/amd64 وlinux/arm64. يسحبها إعداد Codespace عبر develop/docker-compose.image.yml بدلًا من تشغيل bin/build.
  • صور العمليات هي صور كاملة بحاوية واحدة (مثل sharelatex/sharelatex) لاختبار التغيير من البداية إلى النهاية. لا يتحرك الوسم ops:latest إلا عند الدفع إلى server-pro؛ أما طلب السحب فيحصل على وسم مؤرَّخ بالوقت فقط. تُحفظ هذه الصور لمدة 7 أيام وهي مخصصة للاختبار فقط.
  • صور الإصدار هي ما ينشره المستخدمون. يُؤخذ رقم الإصدار من اسم الفرع، لذا فإن release-v6.3.0 ينشر overleaf-pro:6.3.0.
1

تشغيل سير عمل يدويًا

افتح تبويب Actions، واختر سير العمل من الجهة اليسرى، ثم انقر على Run workflow وأكّد. يحتوي Build Operations Image أيضًا على خيار Build without cache لاستخدامه عندما تكون طبقة مخزنة مؤقتًا قديمة.
2

البناء في نسختك المتفرعة (Fork)

تعمل سير العمل نفسها في النسخة المتفرعة: فعّل Actions في نسختك المتفرعة، ثم شغّلها من تبويب Actions الخاص بها. تُدفع الصور إلى ghcr.io/<your-name>/overleaf-pro/... باستخدام GITHUB_TOKEN المدمج، لذا لا حاجة إلى أي أسرار. لا يعمل Sync Upstream Code وتنظيف الصور القديمة إلا في ayaka-notes.يتطلب Build Release Image وجود فرع release-v* في نسختك المتفرعة.
لمعرفة الإيداع الذي بُنيت منه صورة ما: ينتهي وسم صورة العمليات بمعرّف الإيداع المختصر، بينما تحمله صورة الإصدار في التسمية com.overleaf.pro.revision (راجع docker inspect في قسم الأسئلة والأجوبة أدناه).

أسئلة وأجوبة

أولًا، عليك سحب صورة Docker وتشغيل الأمر التالي لفحص التسميات (labels) في صورة Docker هذه:
bash
بعد ذلك يمكنك التحقق مما إذا كان الإيداع (b0d05c0) موجودًا في الفرع master في المصدر الأصلي.
هذا سلوك متوقع. فالإصدار 6.0.1 إصدار تصحيحي بسيط مبني فوق صورة 6.0.0. إذ تُطبَّق التغييرات عبر ترقيع (patching) صورة 6.0.0 الحالية، بدلًا من إعادة بناء الصورة من إيداع جديد. لذلك يكون معرّف الإيداع داخل الصورة متطابقًا بين 6.0.0 و6.0.1.للاطلاع على معلومات مفصلة، راجع hotfix.
آخر تعديل في ٢٠ نوفمبر ٢٠٢٦