ترحيل إعدادات سمة Discourse

توثيق أدلة المطور
1

مقدمة

اعتبارًا من الإصدار 3.2.0.beta3 من Discourse، يمكن لسمات/مكونات Discourse الاستفادة من ميزة الترحيل (migrations) لتطوير وتعديل إعداداتها بسلاسة. تضمن هذه الميزة أن تحديثات السمات لا تعطل التثبيتات الحالية من خلال التعامل مع التغييرات في الإعدادات بطريقة مُتحكم بها.

متى تستخدم الترحيلات

السيناريوهات الشائعة التي تكون فيها الترحيلات مفيدة بشكل خاص:

  • تغيير نوع الإعداد (على سبيل المثال، من سلسلة مفصولة بفواصل إلى قائمة).
  • إعادة تسمية إعداد.
  • تعديل بنية أو تنسيق البيانات المخزنة في إعداد ما.

في هذه السيناريوهات، إذا تم تغيير نوع الإعداد أو اسمه في ملف settings.yml دون ترحيل مصاحب، فإن التثبيتات الحالية التي تم فيها تغيير الإعداد عن القيمة الافتراضية ستفقد التغيير الذي أجرته على الإعداد وقد تتعطل عند تحديث السمة.

لضمان انتقال سلس عند تحديث إعداد السمة، يجب على مطوري السمات شحن ترحيل يوجه نواة Discourse حول كيفية ترحيل الحالة الحالية التي تتوافق مع الإصدار القديم من settings.yml إلى الإصدار الجديد.

ملفات الترحيل

الترحيلات هي ملفات JavaScript تقع في الدليل migrations/settings الخاص بالسمة، وتتبع اصطلاح التسمية XXXX-migration-name.js. البادئة XXXX هي رقم إصدار، يبدأ من 0001 ويزداد بالتسلسل، وهو ما يحدد ترتيب التنفيذ.

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

نوصي بالبدء بـ 0001 للترحيل الأول و 0002 للترحيل الثاني وما إلى ذلك. لاحظ أنه إذا كان إصدار الترحيل أقل من 1000، فيجب حشو الرقم بأصفار بادئة لجعله مكونًا من 4 أرقام نظرًا لأنه يجب أن يبدأ اسم ملف الترحيل بـ 4 أرقام. لنفس السبب، ليس من الممكن حاليًا وجود أكثر من 9999 ترحيلًا في سمة ما، ولكن قد نغير ذلك في المستقبل.

دالة الترحيل

الميزات القياسية لـ JavaScript مثل الفئات (classes)، والدوال (functions)، والمصفوفات (arrays)، والخرائط (maps) وما إلى ذلك، كلها متاحة لاستخدامها في الترحيلات. التوقع الوحيد من نواة Discourse هو أن يقوم كل ملف ترحيل بتصدير دالة افتراضية تعمل كنقطة دخول. تستقبل هذه الدالة كائن 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;
}

التنفيذ ومعالجة الأخطاء

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

إذا كان هناك خطأ برمجي في ترحيل يؤدي إلى تلف حالة إعداد ما، فإن الطريقة الصحيحة لإصلاح المشكلة هي إنشاء ترحيل جديد يصحح الحالة التالفة بدلاً من تعديل الترحيل الأصلي.

يتم التحكم في إصدار هذه الوثيقة - اقترح تغييرات على github.

8 إعجابات
Add settings to your Discourse theme