تثبيت إصدارات الإضافات والقوالب لإصدارات Discourse الأقدم (فروع d-compat)

[Discourse]

الخلفية

يريد مطورو السمات والإضافات عادةً استهداف إصدار latest من Discourse دون القلق بشأن التوافق مع الإصدارات الأقدم. لكن المواقع التي تعمل بإصدارات أقدم من Discourse لا تزال بحاجة إلى نسخة من السمة أو الإضافة تعمل معها.

لسد هذه الفجوة، يمكن إخبار Discourse بفحص إصدار “مُثبت” (pinned) أقدم من السمة أو الإضافة. هناك آليتان للقيام بذلك، يتم فحصهما بالترتيب التالي:

1. فروع d-compat/<YYYY>.<M> في مستودع السمة/الإضافة (الطريقة الأساسية — موصى بها لجميع التثبيتات الجديدة).
2. ملف YAML .discourse-compatibility في الجذر من المستودع (الآلية الأصلية، لا تزال مدعومة كحل احتياطي).

إذا وُجد كلاهما، فإن الفرع هو الذي يُؤخذ.

نظام فرع d-compat/<YYYY>.<M>

تستخدم إصدارات Discourse إصدارات قائمة على التاريخ مثل 2025.5، 2025.6، إلخ. عندما يقوم Discourse بتحديث إضافة أو سمة من Git، يسأل المستودع: «هل لديك فرع باسم d-compat/<YYYY>.<M> يتطابق مع إصداري؟» (على سبيل المثال d-compat/2025.5 لإصدار Discourse 2025.5.x). إذا كان الأمر كذلك، يقوم Discourse بفحص نهاية ذلك الفرع بدلاً من الفرع main.

يتم تشغيل عملية البحث فقط عندما يكون النسخ المحلي على الفرع الافتراضي للمستودع. إذا قمت بتثبيت فرع مختلف عمدًا، يتم تخطي منطق d-compat ويتم احترام تثبيتك.

لدعم إصدار أقدم من Discourse باستخدام هذا النظام:

1. أنشئ فرعًا باسم d-compat/<YYYY>.<M> من التزامن (commit) معروف بأنه يعمل على ذلك الإصدار (على سبيل المثال git checkout -b d-compat/2025.5 <commit>).
2. ادفعه إلى origin. قد ترغب في حماية الفرع من الحذف العرضي.
3. ادمج أي التزامنات المنقولة (backport commits) في ذلك الفرع. ستقوم مثيلات Discourse على 2025.5.x بجلبها تلقائيًا في التحديث التالي؛ بينما ستستمر المثيلات على إصدارات Discourse الأحدث في تتبع الفرع الافتراضي.

لا تحتاج إلى لمس ملف .discourse-compatibility على الإطلاق عند استخدام الفروع.

إنشاء الفروع تلقائيًا (create-d-compat-branch.yml)

في الممارسة العملية، نادرًا ما تحتاج إلى إنشاء هذه الفروع يدويًا. تتضمن هياكل السمات والإضافات الافتراضية d-compat-branch.yml سير عمل يعمل يوميًا، يتحقق من الإصدارات الجديدة من نواة Discourse، ويدفع فروع d-compat/<YYYY>.<M> المطابقة حسب الحاجة.

إذا تم إنشاء مستودعك من نسخة أقدم من الهياكل، فما عليك سوى نسخ ملف d-compat-branch.yml إلى مجلد .github/workflows لديك لتفعيله.

نقل إصلاح إلى فرع d-compat

عندما تقوم بدمج إصلاح في الفرع الافتراضي والذي يحتاج أيضًا إلى الوصول إلى مواقع تعمل بإصدار أقدم من Discourse:

1. أنشئ فرعًا من فرع d-compat المستهدف واختر الإصلاح:

   git fetch origin
   git checkout -b backport/my-fix-2025.5 origin/d-compat/2025.5
   git cherry-pick <commit-sha>
   git push -u origin backport/my-fix-2025.5
   

2. افتح طلب سحب (PR) مع d-compat/2025.5 كـ الفرع الأساسي (وليس main). قم بمراجعته ودمجه بنفس الطريقة التي تفعلها مع أي طلب سحب آخر.

3. كرر العملية لكل فرع قديم من فروع d-compat/<YYYY>.<M> الذي يحتاج إلى الإصلاح.

ستقوم المواقع على 2025.5.x بجلب الالتزام المدمج في تحديثها التالي.

الاحتياطي القديم: ملف `.discourse-compatibility`

إذا لم يكن هناك فرع d-compat مطابق، يعود Discourse إلى ملف YAML .discourse-compatibility في جذر المستودع، الذي يربط إصدارات Discourse بإحالات Git الخاصة بالإضافة/السمة الخاصة بك:

< 3.2.0.beta2-dev: abcde

يختار Discourse الإدخال الأدنى الذي يتطابق مع إصدار النواة قيد التشغيل، لذا يقوم أي شخص على < 3.2.0.beta2-dev بفحص الالتزام abcde. استخدم < (أو <= القديمة، وهي الافتراضية عند عدم تقديم مشغل) لتحديد حد الإصدار. اعتمد على هذا فقط إذا لم يتمكن النظام القائم على الفروع من التعبير عن ما تحتاجه.

---

يتم التحكم في إصدار هذا المستند — اقترح تغييرات على GitHub.

[NateDhaliwal]

إذا كان الإصدار < 3.5.0.beta8-dev، فهل سيشمل 3.5.0؟

[david (David Taylor)]

لا. يُعتبر الإصدار 3.5.0 “أعلى” من الإصدار التجريبي “3.5.0.beta8-dev”.

يمكنك دائمًا تجربة المقارنات على وحدة تحكم Ruby:

> Gem::Version.new("3.5.0") < Gem::Version.new("3.5.0.beta8-dev")
=> false

[NateDhaliwal]

مفهوم. شكرا على الشرح!

[david (David Taylor)]

تم تحديث هذه الوثيقة لوصف استراتيجية d-compat/* الجديدة من https://meta.discourse.org/t/rfc-a-new-versioning-strategy-for-discourse/383536، والتي أصبحت متاحة للاستخدام الآن.