مقدمة
بدءًا من الإصدار 3.2.0.beta3 من Discourse، يمكن لسلاسل و مكونات السمات (themes/components) في Discourse الاستفادة من ميزة التنقلات (migrations) لتطهير وتعديل إعداداتها بسلاسة. تضمن هذه الميزة أن تحديثات السمات لا تعطل التثبيتات الحالية من خلال التعامل مع التغييرات في الإعدادات بشكل مُتحكَّم فيه.
متى تستخدم التنقلات
حالات شائعة تكون فيها التنقلات مفيدة بشكل خاص:
- تغيير نوع الإعداد (على سبيل المثال، من سلسلة مفصولة بفواصل إلى قائمة).
- إعادة تسمية إعداد.
- تعديل بنية أو تنسيق البيانات المخزنة في الإعداد.
في هذه الحالات، إذا تم تغيير نوع الإعداد أو اسمه في ملف settings.yml دون وجود تنقلة مصاحبة، فإن التثبيتات الحالية التي تم فيها تغيير الإعداد عن القيمة الافتراضية ستفقد التغيير الذي أجراه المستخدم على الإعداد وقد تتعطل عند تحديث السمة.
لضمان انتقال سلس عند تحديث إعداد السمة، يجب على مطوري السمات تضمين تنقلة تُعلِم نواة Discourse كيفية نقل الحالة الحالية المطابقة للإصدار القديم من settings.yml إلى الإصدار الجديد.
ملفات التنقلة
التنقلات هي ملفات JavaScript موجودة في مجلد migrations/settings داخل السمة، وتتبع convention التسمية XXXX-migration-name.js. البادئة XXXX هي رقم إصدار، يبدأ من 0001 ويتزايد بالتتابع، ويحدد ترتيب التنفيذ.
يجب أن يكون الاسم وصفًا موجزًا لغرض التنقلة، ومقتصرًا على الأحرف الأبجدية الرقمية والشرطات، وأقل من 150 حرفًا في الطول. يتم تنفيذ التنقلات بترتيب تصاعدي بناءً على القيمة الرقمية لإصداراتها.
نوصي بأن تبدأ بـ 0001 للتنقلة الأولى و 0002 للتنقلة الثانية، وهكذا. لاحظ أنه إذا كان إصدار التنقلة أقل من 1000، فيجب ملء الرقم بأصفار بادئة لجعله مكونًا من 4 أرقام، حيث يجب أن يبدأ اسم ملف التنقلة بـ 4 أرقام. لنفس السبب، لا يمكن حاليًا تضمين أكثر من 9999 تنقلة في السمة، لكن قد يتغير ذلك في المستقبل.
دالة التنقلة
جميع ميزات JavaScript القياسية features مثل الفئات (classes)، والدوال (functions)، والمصفوفات (arrays)، والخرائط (maps)، وما إلى ذلك، متاحة للاستخدام في التنقلات. التوقع الوحيد من نواة Discourse هو أن كل ملف تنقلة يجب أن يصدّر دالة افتراضية (default function) تعمل كنقطة دخول. تستقبل هذه الدالة كائن Map يمثل الإعدادات المعدلة للسمة وتعيد كائن Map يعكس الحالة النهائية المرغوبة لجميع الإعدادات.
أمثلة
إعادة تسمية إعداد السمة:
// filename: 0001-rename-old-setting.js
export default function migrate(settings) {
if (settings.has("old_setting_name")) {
settings.set("new_setting_name", settings.get("old_setting_name"));
settings.delete("old_setting_name");
}
return settings;
}
يجب أن تُرافَق هذه التنقلة بإعادة تسمية الإعداد في ملف settings.yml.
تحويل إعداد سلسلة مفصولة بفواصل إلى قائمة مناسبة:
// filename: 0001-convert-string-setting-to-list.js
export default function migrate(settings) {
if (settings.has("list_setting")) {
const list = settings.get("list_setting").split(",");
settings.set("list_setting", list.join("|"));
}
return settings;
}
على غرار المثال السابق، يجب أن تُرافَق هذه التنقلة بتغيير نوع الإعداد من string إلى list في ملف settings.yml.
إعادة تسمية خيار في إعداد enum:
// filename: 0001-rename-enum-choice.js
export default function migrate(settings) {
if (settings.get("enum_setting") === "old_option") {
settings.set("enum_setting", "new_option");
}
return settings;
}
إضافة عنصر جديد إلى إعداد قائمة:
// filename: 0001-add-item-to-list.js
export default function migrate(settings) {
if (settings.has("list_setting")) {
const list = settings.get("list_setting").split("|");
list.push("new_item");
settings.set("list_setting", list.join("|"));
} else {
settings.set("list_setting", "new_item");
}
return settings;
}
نقل إعداد نصي إلى ترجمة السمة
استخدم helpers.migrateSettingToTranslation(settingName, translationKey) عند استبدال إعداد نصي بترجمة للسمة:
// filename: 0002-migrate-heading.js
export default function migrate(settings, helpers) {
helpers.migrateSettingToTranslation("heading_text", "homepage.heading");
return settings;
}
أزل heading_text من settings.yml واعلن الوجهة في locales/en.yml في التحديث نفسه:
en:
homepage:
heading: ""
ينقل المساعد الإعداد المحفوظ إلى تجاوز ترجمة السمة باللغة الإنجليزية ويزيل الإعداد. اللغة الإنجليزية هي لغة الرجوع (fallback locale) للغات الأخرى، لذا يستمر الزوار في رؤية النص المحفوظ حتى يتم توفير ترجمة لخاصتهم المحلية. ملف اللغة الذي يعلن المفتاح نفسه، حتى مع قيمة فارغة، يخفي النص الإنجليزي المحفوظ لتلك اللغة المحلية. ينطبق هذا أيضًا على ملفات اللغة المضافة في التحديثات المستقبلية.
- يقرأ المساعد من خريطة
settingsالممررة إلى التنقلة. يتم نقل الإعدادات المحفوظة فقط. إذا كان الإعداد القديم يحتوي على قيمة افتراضية غير فارغة، فاستخدم تلك القيمة الافتراضية فيen.ymlحتى تحتفظ المواقع التي لا تحتوي على قيمة محفوظة بنصها. - يجب أن تكون قيمة الإعداد نصًا ويجب أن تكون الوجهة مفتاح نص معتمد. يتم الحفاظ على السلاسل الفارغة.
- لا يتم تجاوز التجاوزات الإنجليزية الموجودة، بما في ذلك الفارغة. إذا استهدفت عدة تنقلات المفتاح نفسه، فإن القيمة المنقولة أولاً هي التي تُلزم.
- يجهز المنفذ تغييرات الترجمة دون الكتابة في قاعدة البيانات. يحفظ Discourse هذه التغييرات في نفس المعاملة (transaction) الخاصة بالإعدادات وسجلات التنقلات؛ فشل التحديث يؤدي إلى إعادة كل شيء إلى ما كان عليه (rollback).
- يحتفظ سجل التنقلة بقيمة الإعداد المحذوف. عدم تغيير رمز السمة لا ينقل تجاوزات الترجمة مرة أخرى إلى الإعدادات.
التنفيذ ومعالجة الأخطاء
تعمل التنقلات تلقائيًا أثناء تثبيت وتحديث السمة. يتم تنفيذها مرة واحدة فقط؛ إذا تم تعديل تنقلة بعد تنفيذ ناجح، فلن تعمل مرة أخرى. إذا فشلت التنقلة، يتوقف عملية التحديث، ويتم تقديم رسالة خطأ توضح ما حدث.
إذا كانت التنقلة تحتوي على خطأ (bug) يؤدي إلى حالة تالفة لإعداد ما، فالطريقة الصحيحة لإصلاح المشكلة هي إنشاء تنقلة جديدة تصحح الحالة التالفة بدلاً من تعديل التنقلة الأصلية.
هذه الوثيقة متحكم بها بالإصدارات (version controlled) - اقترح التغييرات على github.