configlet sync

Синхронізація даних вправи з репозиторієм problem-specifications

Практичну вправу на треку Exercism часто реалізують за специфікацією з репозиторію exercism/problem-specifications.

Exercism свідомо вимагає, щоб кожна вправа мала власну копію певних файлів (як-от .docs/instructions.md), навіть якщо ця вправа вже є в problem-specifications. Тому в configlet є команда sync, яка може перевірити, чи такі практичні вправи на треку синхронізовані з цим репозиторієм-джерелом, і оновити їх, коли є доступні оновлення.

З problem-specifications можна оновлювати три види даних: документацію, метадані й тести. Є також один вид даних, який можна заповнити з файлу config.json рівня треку: шляхи до файлів у конфігураційних файлах вправ.

Перевірку й оновлення цих видів даних ми описуємо в окремих розділах нижче, але ось короткий підсумок:

• configlet sync працює лише з тими вправами, які є у файлі config.json рівня треку. Тому якщо ми реалізуємо нову вправу на треку й хочемо створити початкові файли за допомогою configlet sync, спершу додамо цю вправу до файлу config.json рівня треку. Якщо вправа ще не готова до показу користувачам, встановімо її значення status як wip.
• Запуск configlet sync без опцій нічого не змінює на треку й перевіряє всі види даних для кожної вправи.
• Щоб працювати з підмножиною видів даних, скористаймося якоюсь комбінацією опцій --docs, --filepaths, --metadata і --tests.
• Щоб оновлювати дані на треку в інтерактивному режимі, скористаймося опцією --update.
• Щоб неінтерактивно оновити документацію, шляхи до файлів і метадані на треку, скористаймося --update --yes.
• Щоб неінтерактивно включити кожен ще не бачений тест для певної вправи, скористаймося, наприклад, --update --tests include --exercise prime-factors.
• Щоб не завантажувати репозиторій problem-specifications, додамо --offline --prob-specs-dir /path/to/local/problem-specifications
• Зауважмо, що під час оновлення configlet sync намагається зберегти порядок ключів у файлах .meta/config.json вправ. Щоб записати ці файли в канонічній формі без синхронізації, скористаймося командою configlet fmt. Однак configlet sync усе ж додає обовʼязкові ключі (authors, files, blurb), можливо порожні, якщо їх немає. Це менш «схоже на синхронізацію», зате зручніше: під час реалізації нової вправи можна скористатися sync, щоб створити початковий файл .meta/config.json.
• configlet sync видаляє ключі, яких немає в специфікації. Власні пари ключ-значення все одно підтримуються: їх треба записувати всередині обʼєкта JSON із назвою custom.
• Код виходу дорівнює 0, якщо на момент завершення configlet усі побачені дані синхронізовано, і 1 в іншому разі.

Зауважмо, що у випусках configlet 4.0.0-alpha.34 і раніших команда sync працювала лише з тестами.

Використання

Команду sync можна використовувати, щоб перевіряти або оновлювати документацію, метадані й тести практичних вправ із «problem-specifications». Нею також можна перевіряти або заповнювати відсутні значення files для концептуальних і практичних вправ із файлу config.json рівня треку.

configlet [global-options] sync [command-options]

Global options:
  -h, --help                   Show this help message and exit
      --version                Show this tool's version information and exit
  -t, --track-dir <dir>        Specify a track directory to use instead of the current directory
  -v, --verbosity <verbosity>  The verbosity of output. Allowed values: q[uiet], n[ormal], d[etailed]

Options for sync:
  -e, --exercise <slug>        Only operate on this exercise
  -p, --prob-specs-dir <dir>   Use this 'problem-specifications' directory, rather than cloning temporarily
  -o, --offline                Do not check that the directory specified by --prob-specs-dir is up to date
  -u, --update                 Prompt to update the seen data that are unsynced
  -y, --yes                    Auto-confirm prompts from --update for updating docs, filepaths, and metadata
      --docs                   Sync Practice Exercise '.docs/introduction.md' and '.docs/instructions.md' files
      --filepaths              Populate empty 'files' values in Concept/Practice exercise '.meta/config.json' files
      --metadata               Sync Practice Exercise '.meta/config.json' metadata values
      --tests [mode]           Sync Practice Exercise '.meta/tests.toml' files.
                               The mode value specifies how missing tests are handled when using --update.
                               Allowed values: c[hoose], i[nclude], e[xclude] (default: choose)

Документація

Практична вправа, похідна від репозиторію problem-specifications, повинна мати файл .docs/instructions.md (а можливо, і файл .docs/introduction.md) з документацією вправи з problem-specifications.

Щоб перевірити всі практичні вправи на треку на наявність оновлень документації (з ненульовим кодом виходу, якщо є хоч одне доступне оновлення):

configlet sync --docs

Щоб інтерактивно оновити документацію для всіх практичних вправ, додамо опцію --update (або -u для стислості):

configlet sync --docs --update

Щоб неінтерактивно оновити документацію для всіх практичних вправ, додамо опцію --yes (або -y для стислості):

configlet sync --docs --update --yes

Щоб працювати з однією практичною вправою, скористаймося опцією --exercise (або -e для стислості). Наприклад, щоб неінтерактивно оновити документацію для вправи prime-factors:

configlet sync --docs -uy -e prime-factors

Метадані

Кожна вправа на треку повинна мати файл .meta/config.json. Для практичної вправи, похідної від репозиторію problem-specifications, цей файл має містити пари ключ-значення blurb, source і source_url, які є у відповідному файлі metadata.toml із репозиторію-джерела.

Щоб перевірити всі практичні вправи на наявність оновлень метаданих (з ненульовим кодом виходу, якщо є хоч одне доступне оновлення):

configlet sync --metadata

Щоб інтерактивно оновити метадані для всіх практичних вправ, додамо опцію --update (або -u для стислості):

configlet sync --metadata --update

Щоб неінтерактивно оновити метадані для всіх практичних вправ, додамо опцію --yes (або -y для стислості):

configlet sync --metadata --update --yes

Щоб працювати з однією практичною вправою, скористаймося опцією --exercise (або -e для стислості). Наприклад, щоб неінтерактивно оновити метадані для вправи prime-factors:

configlet sync --metadata -uy -e prime-factors

Тести

Якщо трек реалізує вправу, для якої в репозиторії problem-specifications є тестові дані, вправа повинна містити файл .meta/tests.toml. Мета файлу tests.toml - відстежувати, які тести реалізовано у вправі. Тести в цьому файлі ідентифікуються за їхнім UUID, і кожен тест має булеве значення (англ. Boolean), яке вказує, чи реалізовано його у вправі.

Файл tests.toml має такий формат:

# This is an auto-generated file.
#
# Regenerating this file via `configlet sync` will:
# - Recreate every `description` key/value pair
# - Recreate every `reimplements` key/value pair, where they exist in problem-specifications
# - Remove any `include = true` key/value pair (an omitted `include` key implies inclusion)
# - Preserve any other key/value pair
#
# As user-added comments (using the # character) will be removed when this file
# is regenerated, comments can be added via a `comment` key.
[1e22cceb-c5e4-4562-9afe-aef07ad1eaf4]
description = "basic"
[79ae3889-a5c0-4b01-baf0-232d31180c08]
description = "lowercase words"
[ec7000a7-3931-4a17-890e-33ca2073a548]
description = "invalid input"
include = false
comment = "excluded because we don't want to add error handling to the exercise"

У цьому випадку трек обрав реалізувати два з трьох доступних тестів. Якщо трек використовує генератор тестів, щоб згенерувати набір тестів для вправи, він повинен використати вміст файлу tests.toml, щоб визначити, які тести включити до згенерованого набору тестів.

Щоб перевірити кожен файл tests.toml практичної вправи на наявність оновлень тестів (з ненульовим кодом виходу, якщо є хоч один тестовий випадок, який є в канонічних даних вправи, але відсутній у tests.toml):

configlet sync --tests

Щоб інтерактивно оновити файл tests.toml для всіх практичних вправ, додамо опцію --update:

configlet sync --tests --update

Для кожного відсутнього тесту це пропонує користувачеві вибрати, включити його, виключити чи пропустити, і відповідно оновлює відповідний файл tests.toml. Configlet записує файл tests.toml вправи, коли користувач завершує вибір для цієї вправи. Це означає, що ми можемо перервати configlet на запрошенні (наприклад, натиснувши Ctrl-C у терміналі) і втратимо рішення щодо синхронізації щонайбільше для однієї вправи.

Щоб неінтерактивно включити кожен ще не бачений тестовий випадок, скористаймося --tests include. Наприклад, щоб зробити це для вправи з назвою prime-factors:

configlet sync --tests include -u -e prime-factors

Не забудьмо насправді реалізувати ці тести на треку!

Шляхи до файлів

Нарешті, команда sync також виконує «синхронізацію» з джерела, яким не є problem-specifications, а саме з файлу config.json рівня треку. Кожна концептуальна вправа і кожна практична вправа повинна мати файл .meta/config.json з обʼєктом files, який задає (відносні) розташування файлів, які використовує вправа. Такі шляхи до файлів зазвичай мають просту закономірність, тож configlet може заповнити значення рівня вправи за закономірностями з ключа files файлу config.json рівня треку.

Щоб перевірити, що кожна концептуальна і практична вправа на треку має повністю заповнений ключ files (або принаймні такий, який не можна заповнити з ключа files рівня треку):

configlet sync --filepaths

(Зауважмо, що configlet lint також видасть помилку, якщо у вправи ключ files відсутній або порожній.)

Щоб заповнити порожні або відсутні значення ключа files рівня вправи для кожної концептуальної і практичної вправи за закономірностями з ключа files рівня треку:

configlet sync --filepaths --update

Щоб зробити це неінтерактивно і для однієї вправи з назвою prime-factors:

configlet sync --filepaths -uy -e prime-factors

Використання sync під час додавання нової вправи на трек

Команда sync стає в пригоді, коли ми додаємо нову вправу на трек. Якщо ми додаємо практичну вправу з назвою foo, яка є в problem-specifications, один із можливих робочих процесів такий:

1. Вручну додамо запис для вправи foo до файлу config.json рівня треку. Після цього вправа стане видимою для configlet sync.
2. Запустімо configlet sync --docs --filepaths --metadata -uy -e foo, щоб створити документацію вправи та початковий файл .meta/config.json із заповненими files, blurb, а можливо, і значеннями source та source_url.
3. Відредагуймо файл .meta/config.json вправи так, як потрібно. Наприклад, додамо себе до масиву authors.
4. Запустімо configlet sync --tests include -u -e foo, щоб створити файл .meta/tests.toml з усіма включеними тестами.
5. Перегляньмо цей файл .meta/tests.toml і додамо include = false до кожного тестового випадку, який вправа не реалізовуватиме.
6. Реалізуймо тести для вправи відповідно до тих, що включені в .meta/tests.toml.
7. Додамо решту обовʼязкових файлів.