Configlet

المواصفات المعيارية لكل ما في Exercism

configlet أداة تساعد المشرفين على المسارات في صيانة مساراتهم.

التدقيق

الوظيفة الأساسية لـ configlet هي إجراء التدقيق: التحقق من أن ملفات (إعدادات) المسار مبنية بشكل صحيح، صياغيًا ودلاليًا. قد لا تتم مزامنة المسارات سيئة الإعداد بشكل صحيح، أو قد تبدو خاطئة على الموقع، أو قد تقدّم تجربة مستخدم أقل من المثالية، لذا تؤدي ضوابط configlet دورًا مهمًا في الحفاظ على سلامة Exercism. يمكن العثور على القائمة الكاملة للقواعد التي يتحقق منها المدقّق هنا.

توليد المستندات

الوظيفة الثانوية لـ configlet هي توليد المستندات. وهناك نوعان من المستندات التي يمكن لـ configlet توليدها:

  1. ملف introduction.md الخاص بتمرين مفاهيمي.
  2. ملف instructions.md الخاص بتمرين تدريبي.

يمكن معرفة كيفية توليد هذه المستندات هنا.

مزامنة بيانات التمارين مع مستودع problem-specifications

الوظيفة الثالثة لـ configlet هي توفير بيانات متنوعة للتمارين التدريبية.

غالبًا ما يُنفَّذ تمرين تدريبي في أحد مسارات Exercism انطلاقًا من مواصفة في مستودع exercism/problem-specifications.

تتطلب Exercism عمدًا أن يكون لكل تمرين نسخته الخاصة من ملفات معيّنة (مثل .docs/instructions.md)، حتى عندما يكون ذلك التمرين موجودًا في problem-specifications. لذلك يوفّر configlet الأمر sync، الذي يمكنه التحقق من أن هذه التمارين التدريبية في المسار متزامنة مع ذلك المصدر الأصلي، ويمكنه تحديثها عند توفّر تحديثات.

هناك ثلاثة أنواع من البيانات يمكن تحديثها من problem-specifications: التوثيق، والبيانات الوصفية، والاختبارات. وهناك أيضًا نوع واحد من البيانات يمكن تعبئته من ملف config.json على مستوى المسار: مسارات الملفات في ملفات إعداد التمارين.

لاحظ أنه في إصدارات configlet 4.0.0-alpha.34 وما قبلها، كان الأمر sync يعمل على الاختبارات فقط.

لمتابعة أي الاختبارات مُنفَّذة لتمرين تدريبي معيّن، يجب أن يحتوي التمرين على ملف .meta/tests.toml. تُعرَّف الاختبارات في هذا الملف بمعرّفها UUID، ولكل اختبار قيمة منطقية تشير إلى ما إذا كان التمرين يُنفّذه.

يمكنك العثور على التفاصيل حول كيفية مزامنة الأجزاء المختلفة من التمرين هنا.

إنشاء الملفات

يمكن استخدام Configlet لإنشاء ملفات بسرعة لأسلوب أو مقال أو تمرين جديد.

يمكنك معرفة المزيد حول كيفية إنشاء هذه الملفات هنا.

توليد معرّفات UUID

تُعرَّف التمارين والمسارات والمفاهيم بمعرّف UUID.

يمكن العثور على كيفية توليد معرّفات UUID هنا.

التنسيق

يمتلك Configlet الأمر fmt للمساعدة في تنسيق ملفات JSON في مستودع المسار بشكل متسق. ينسّق الأمر fmt الملفات التالية:

  • config.json
  • exercises/{concept,practice}/*/.approaches/config.json
  • exercises/{concept,practice}/*/.articles/config.json
  • exercises/{concept,practice}/*/.meta/config.json

يمكنك معرفة المزيد حول أمر التنسيق هنا.

التثبيت

يُوزَّع configlet كملف ثنائي مستقل. ينبغي أن يحتوي كل مسار على سكربت bin/fetch-configlet، وقد يحتوي أيضًا على سكربت bin/fetch-configlet.ps1. الأول سكربت bash، والثاني سكربت PowerShell.

يؤدي تشغيل أحد هذين السكربتين إلى تنزيل أحدث إصدار من configlet إلى مجلد bin. بعد ذلك يمكنك استخدام configlet بتشغيل bin/configlet أو bin/configlet.exe على الترتيب.

CI

ينبغي أن تدمج جميع المسارات وظيفة التدقيق في configlet ضمن إعداد CI الخاص بها. أسهل طريقة لفعل ذلك هي استخدام إجراء GitHub الخاص بـ configlet CI.