تقدم طلبات الاندماج (PRs) المفتوحة الاثنتان بنهجين مختلفين لتحرير سمات BBCode في النص الخام للمشاركات:
-
#43187 — إضافة وضع موضوع الخلف للحدث المتكرر يقدم
BbcodeRewriter، والذي يحدد الحدث المُعرض ويعيد كتابة وسم BBCode الافتتاحي المقابل له بأمان أثناء التمرير التلقائي. -
#42932 — إضافة إجراءات الأحداث إلى سير العمل يقدم
PrettyText.update_bbcode_attributes، والذي يحدد كتلة BBCode المُحللة ويحدّث سماتها عندما تفتح سير العمل حدثًا أو تغلقه.
أثناء مراجعة #43187، اقترح مارتن استخراج وظائف معالجة BBCode العامة من الخدمة الخاصة بالأحداث.
شملت مسودةي الأولية بعض الوظائف القائمة على الرموز المميزة (token-based) من طلب الاندماج الآخر، لكن هذا أدى إلى إدخال آليتي إعادة كتابة داخل #43187. وبما أن واجهة برمجة التطبيقات (API) القائمة على الرموز المميزة لم يكن لها أي مستدعي إنتاج في ذلك الفرع، فقد أزلتها في الإصدار 6d13371.
تظل واجهة برمجة التطبيقات القائمة على الرموز المميزة مفيدة بشكل مستقل لـ #42932.
تساءلت عما إذا كان ينبغي لهذه النهجين أن يتقاربا في النهاية في واجهة API أساسية واحدة قابلة لإعادة الاستخدام، أم أن متطلباتهما المختلفة تبرر الاحتفاظ بكليهما.
مقارنة بين التنفيذين الحاليين
تصف الجدول ما تنفذه الأكواد حاليًا، بدلاً من اقتراح أن أحد النهجين خاطئ بطبيعته.
| القدرة | BbcodeRewriter (#43187) |
واجهة API القائمة على الرموز المميزة (#42932) | المعنى والأهمية |
|---|---|---|---|
| 1. استخدام محلل BBCode الخاص بـ Discourse | يفحص الوسوم الافتتاحية المرشحة باستخدام parseBBCodeTag، وهو نفس قواعد الوسم الافتتاحي المستخدمة بواسطة محرك Markdown. |
يستخدم DiscourseMarkdownIt.parse للحصول على رموز Markdown وإيجاد كتلة BBCode مطابقة. |
كلا النهجين يفهمان صياغة BBCode، بدلاً من الاعتماد حصريًا على تعبير نمطي مستقل. يختلفان في كيفية تحديد الوسم المطلوب تحريره. |
| 2. اختيار كتلة BBCode المستهدفة | يضع علامات مؤقتة على الوسوم الافتتاحية المرشحة، يعرض المشاركة، ويحدد المرشح المقابل لعنصر HTML محدد، مثل div.discourse-post-event. |
يختار أول رمز BBCode مُحلل يطابق اسم الوسم المطلوب في meta.bbcode. |
هوية الهدف مهمة. يحتاج #43187 إلى ربط BBCode الخام بالحدث الذي عرضه Discourse فعليًا. يستخدم سير عمل #42932 أول كتلة حدث مُحللة مطابقة. |
| 3. التعامل مع الأهداف المفقودة أو الغامضة | يرمي TargetNotFound أو AmbiguousTarget أو UnsupportedRenderer عندما لا يمكن تحديد الهدف بشكل موثوق. |
يعيد null إذا لم توجد كتلة مُحللة مطابقة؛ وإلا يختار التطابق الأول. |
سلوك الفشل يختلف. يرفض #43187 عمدًا التحرير التلقائي الغامض. قد يكون اختيار أول كتلة مُحللة كافيًا عندما يتوقع المستدعي وجود كتلة ذات صلة واحدة فقط. |
| 4. التحقق من التحويل من الخام إلى المُعرض | يعرض المحتوى الموسوم، يتحقق من العلامة على عنصر HTML المقصود، ويتأكد من أن إدراج وإزالة العلامة لا يغيران HTML المُعرض. | يستخدم بيانات رموز محلل Markdown لتحديد الوسم الافتتاحي دون فحص هوية إضافي لـ HTML المُعرض. | هذا يحمي من تحرير الهدف المُعرض الخطأ. وهو ذو صلة خاصة عندما يؤرشف مهمة خلفية حدثًا موجودًا تلقائيًا، لكنه يتضمن عرضًا إضافيًا وتعقيدًا. |
| 5. فحص الوسم الافتتاحي المختار | قبل إعادة الكتابة، يفحص النص الخام المُقدم مرة أخرى ويتحقق من أن المرشح المختار ما زال يطابق نص الوسم الافتتاحي المتوقع. | يحدد الوسم الافتتاحي المطابق أثناء نداء التحديث دون مقارنة متوقعة منفصلة للافتتاح. | هذا فحص اتساق داخلي. يساعد في تجنب إعادة كتابة مرشح لم يعد يطابق الاختيار السابق. وليس بحد ذاته حماية ضد التعديلات المتزامنة على قاعدة البيانات. |
| 6. التعامل مع أسماء السمات والقيم الموجودة | يعيد كتابة السمات المحددة باستخدام حدود السمة الخاصة بالمحلل. كما يقوم بتطبيع أسماء السمات المُعرضة المكافئة، مما يسمح بإزالة المتغيرات مثل Recurrence و recurrence بشكل متسق. |
يستخدم تطابقات رموز السمة لاستبدال أو إزالة الأسماء المطلوبة ومُخارج السمة المشترك لـ BBCode لإدراج القيم. | يهدف كلاهما إلى الحفاظ على السمات غير المتعلقة. تطبيع الأسماء المكافئة مهم بشكل خاص عند أرشفة حدث، لأن ترك مستعار للتكرار قد يؤدي إلى بقاء الحدث المكتمل متكررًا. |
| 7. التحقق من الوسم المُعاد كتابته | يحلل الوسم الافتتاحي المُعاد كتابته مرة أخرى ويتحقق من أن سماته تطابق القيم المقصودة. يرمي الرحلة الدائرية غير الصالحة خطأً. | ينتج الوسم الافتتاحي المُعاد كتابته مباشرة، دون خطوة تحليل ومقارنة نهائية مكافئة. | التحقق من الرحلة الدائرية يكشف عن مشاكل التسلسل، مثل قيم السمات المتغيرة أو الحدود غير الصالحة. النهج القائم على الرموز المميزة أبسط لكنه يعتمد على منطق إعادة كتابته واختباره بدلاً من هذا الفحص الإضافي وقت التشغيل. |
| 8. الحفاظ على محتوى المشاركة غير المرتبط | يغير الوسم الافتتاحي المختار مع الاحتفاظ بمحتوى الخام المحيط. كما يتحقق من بقاء قيم السمات غير المتعلقة بعد إعادة الكتابة. | يستبدل جزء الوسم الافتتاحي المختار مع الاحتفاظ بمحتوى الخام المحيط والسمات غير المطلوبة للتعديل. | يتعين على كلاهما تجنب تغييرات غير مقصودة في المشاركة. يجب ألا يعدّل تحرير متعلق بحدث المناقشة المحيطة أو سمات BBCode غير المتعلقة بصمت. |
| 9. تكلفة التنفيذ | يتطلب فحص المرشحين، العلامات المؤقتة، عرض المشاركة، فحص HTML، إعادة كتابة السمات والتحقق. | يحلل رموز Markdown، يختار أول وسم افتتاحي مطابق ويعيد كتابته مباشرة. | الفحوصات الأقوى وقت التشغيل لها تكلفة. السؤال هو ما إذا كانت الضمانات الإضافية يجب أن تكون متاحة لجميع المستدعين، اختيارية، أو تُنفذ فقط حيث تتطلبها التطبيق. |
لماذا تختلف المتطلبات
بالنسبة لـ #43187، يعمل التمرير للخلف تلقائيًا عندما ينتهي تكرار. يُؤرشف الحدث الأصلي كتكرار غير متكرر، ويُنشأ موضوع جديد للتكرار التالي.
إذا تم تعديل كتلة [event] الخاطئة، أو لم تعد السمات المُعاد كتابتها تمثل الحدث المقصود، فقد يستمر الخطأ عبر محاولات التمرير التلقائي.
بالنسبة لـ #42932، يطلب إجراء سير العمل صراحةً فتح حدث أو إغلاقه. يعيد تنفيذها الحالي القائم على الرموز المميزة كتلة الحدث المطابقة الأولى المُحللة.
لذلك، ليس النهج القائم على الرموز المميزة غير مناسب بالضرورة لهذا الاستخدام. إنه ببساطة يوفر ضمانات اختيار وتحقق مختلفة.
تشارك كلا النهجين بالفعل بعض البنية التحتية الأساسية، بما في ذلك parseBBCodeTag و serializeBBCodeAttr.
اتجاه محتمل لتجريد مشترك
قد تكون إحدى الاحتمالات فصل ثلاث مسؤوليات:
-
إيجاد وسم BBCode افتتاحي — باستخدام رموز المحلل، اختيار المرشحين الصريح، أو خرائط عناصر العرض.
-
إعادة كتابة سماته — باستخدام تنفيذ مشترك واحد لحدود السمات، التسلسل، والحفاظ على القيم غير المتعلقة.
-
التحقق من النتيجة — فرض هوية الهدف، كشف الغموض، تكافؤ المحتوى المعروض، أو فحوصات رحلة السمة الدائرية اختياريًا، اعتمادًا على المستدعي.
قد يتيح ذلك لسير العمل الأبسط استخدام اختيار رموز مباشر بينما تطلب عمليات التحرير التلقائي الحساسة ضوابط أمان أقوى.
ومع ذلك، قد يؤدي أيضًا إلى تعقيد غير ضروري مقارنة بالحفاظ على واجهتي API أصغر.
سؤال للمحافظين
هل سيكون من الأفضل لطلبات الاندماج الاثنين الاحتفاظ بواجهات إعادة الكتابة المنفصلة لديهما، نظرًا لمتطلبات اختيار الأهداف المختلفة لديهما؟
أو هل سيكون مُعيد كتابة سمة منخفض المستوى مشترك مع اختيار هدف وتحقق قابل للتهيئة اتجاهًا أفضل على المدى الطويل؟
أنا مهتم بشكل خاص بما إذا كانت فحوصات السلامة الإضافية التي تنفذها حاليًا BbcodeRewriter تعتبر وظيفة أساسية عامة مفيدة، أم ينبغي أن تبقى محددة لحالات الاستخدام التي تحتاج إلى ضمانات أقوى.
لا أقترح أن أي طلب اندماج بحاجة إلى منع الآخر؛ الهدف هو تجنب التكرار غير الضروري في بنية BBCode الأساسية في Discourse مع تطور الميزات الاثنتين.