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, і кожен тест має булеве значення (англ. Boolean), яке вказує, чи реалізовано його в цій вправі.

Докладніше про те, як синхронізувати різні частини вправи, читайте тут.

Створення файлів

За допомогою 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.