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 سطح مسیر پر کرد: مسیرهای فایل در فایل‌های پیکربندی تمرین.

توجه کنید که در نسخه‌های 4.0.0-alpha.34 و پیش‌ترِ configlet، دستور 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

می‌توانید درباره‌ی دستور format بیشتر اینجا بخوانید.

نصب

configlet به‌صورت یک فایل اجرایی مستقل توزیع می‌شود. هر مسیر باید یک اسکریپت bin/fetch-configlet داشته باشد و ممکن است اسکریپت bin/fetch-configlet.ps1 را هم داشته باشد. اولی یک اسکریپت bash است و دومی یک اسکریپت PowerShell.

اجرای یکی از این اسکریپت‌ها آخرین نسخه‌ی configlet را در پوشه‌ی bin دانلود می‌کند. سپس می‌توانید با اجرای bin/configlet یا bin/configlet.exe به‌ترتیب از configlet استفاده کنید.

CI

همه‌ی مسیرها باید قابلیت لینت configlet را در راه‌اندازی CI خود بگنجانند. ساده‌ترین راه انجام این کار استفاده از اکشن configlet CI در GitHub است.