Додати практичну вправу

У цьому документі пояснюється, як додати нову практичну вправу.

Вибір вправи

Найпростіший спосіб перевірити, які практичні вправи ще не реалізовано, - перейти на сторінку збірки треку (наприклад, https://exercism.org/tracks/csharp/build) і подивитися розділ «Practice Exercises».

Caution

Дані на сторінці збірки оновлюються раз на добу.

Створення каркаса вправи

Швидко створити каркас нової практичної вправи можна, запустивши скрипт bin/add-practice-exercise (джерело) з кореневого каталогу треку:

bin/add-practice-exercise <exercise-slug>

За бажанням можна також указати складність вправи (через -d) та/або імʼя користувача автора на GitHub (через -a):

bin/add-practice-exercise -d 3 -a foobar <exercise-slug>
Note

Якщо в репозиторії треку немає цього файлу, його можна вільно скопіювати у свій репозиторій за посиланням на джерело вище.

Реалізація вправи

Після створення каркасних файлів потрібно буде:

  • Додати тести до файлу тестів
  • Додати приклад реалізації
  • Визначити вміст файлу-заглушки
  • У файлі .meta/config.json вправи:
    • Додати імʼя користувача авторів вправи на GitHub до ключа authors
  • У файлі config.json треку:
    • Перевірити/оновити складність вправи
    • Додати концепції до ключа practices (потрібно лише тоді, коли у треку є концептуальні вправи)
    • Додати концепції до ключа prerequisites (потрібно лише тоді, коли у треку є концептуальні вправи)

Додати тести

Важлива частина додавання вправи - це додавання тестів. Загалом кажучи, під час додавання тестів до практичної вправи є два варіанти:

  1. Реалізувати тести з нуля, використовуючи тестові випадки з файлу canonical-data.json вправи, який можна знайти в репозиторії problem-specifications.
  2. Перенести тести з реалізації іншого треку (підказка: перейдіть на https://exercism.org/exercises/<slug>, щоб побачити, які треки реалізували конкретну вправу).

Другий варіант може бути особливо привабливим, бо дає швидкий результат. Але варто памʼятати, що реалізацію слід доопрацювати під свій трек. Наприклад, деякі треки не використовують класи, а працюють лише з функціями. Якщо ж трек зазвичай працює з обʼєктами, реалізацію слід адаптувати до того, що найкраще підходить цьому треку.

Note

Деякі треки використовують генератор тестів, щоб автоматично (пере)генерувати файл(и) тестів вправи. Перевірте документацію треку, чи є там генератор тестів і як ним користуватися.

Додати приклад реалізації

Щоб переконатися, що код, який проходить тести, написати можливо, потрібно додати приклад реалізації.

Note

Код не обовʼязково має бути ідіоматичним, він лише має проходити тести.

Перевірити, що приклад реалізації проходить усі тести, можна, запустивши скрипт bin/verify-exercises (джерело) з кореневого каталогу треку:

bin/verify-exercises <exercise-slug>

За виводом переконайтеся, що приклад реалізації проходить усі тести.

Note

Якщо в репозиторії треку немає цього файлу, його можна вільно скопіювати у свій репозиторій за посиланням на джерело вище.

Advanced

Під капотом скрипт bin/verify-exercises робить кілька речей:

  • Копіює вправу до тимчасового каталогу
  • Перезаписує файл(и)-заглушки файлом(ами) прикладу реалізації
  • Якщо у файлі тестів є тести з позначкою пропуску, її буде знято
  • Запускає тести

Додати файл(и)-заглушки

Файли-заглушки реалізації дають студентові відправну точку.

Ми радимо, щоб файли-заглушки містили мінімальну кількість коду, достатню для того, щоб:

  • студент міг одразу почати реалізовувати логіку, яка проходить тести
  • студент не натрапляв на «дивні» синтаксичні помилки

На практиці це означає визначення функцій/методів, які перевіряє набір тестів. Треки вільні у тому, як саме вони оформлюють цей код, аби лише код-заглушка спочатку не проходив жодного тесту.

Приклади

Python:

def two_fer(name):
    pass

Kotlin:

fun twofer(name: String): String {
    TODO("Implement the function to complete the task")
}

Перевірка вправи лінтером

Останній крок - запустити лінтер, щоб перевірити, чи правильно структуровано (конфігураційні) файли треку, і синтаксично, і семантично.

Спочатку переконайтеся, що встановлено найновішу версію configlet, запустивши:

bin/fetch-configlet

Потім запустіть лінтер, виконавши:

bin/configlet lint

За виводом перевірте, що все гаразд.

Надсилання пул-реквесту

Коли все гаразд, можна надіслати пул-реквест до репозиторію треку.

Перед надсиланням прочитайте Посібник із пул-реквестів для контрибʼюторів і Посібник із пул-реквестів.

Переконайтеся, що в описі PR вказано вправу, яку додають.