На цій сторінці описано, як зробити внесок до матеріалів та проєктів freeCodeCamp, які використовують розширення CodeRoad VS Code.

## Як працюють матеріали

Кожен матеріал freeCodeCamp, який використовує CodeRoad, має власний репозиторій в рамках організації freeCodeCamp GitHub. Всі вони починаються з `learn-`. Наприклад, `https://github.com/freeCodeCamp/learn-bash-by-building-a-boilerplate/`.

Кожен репозиторій матеріалу має гілку `main` та гілку «версії», тобто `v1.0.0`.

Двома основними файлами на гілці `main` є `TUTORIAL.md` та `coderoad.yaml`. `TUTORIAL.md` містить усі інструкції, підказки, заголовки і т. д. для даного матеріалу. `coderoad.yaml` містить інструкції для CodeRoad, наприклад, які команди виконувати й коли, у яких файлах відстежувати зміни, і яку гілку версії використовувати для кроків.

Гілка «версії» містить затвердження, які будуть завантажені на кожному кроці матеріалу. Повідомлення затверджень у цій гілці повинні бути особливими. Перше затвердження має складатися з текстового повідомлення `INIT` та містити всі файли, які необхідно завантажити перед першим уроком.

Послідовні повідомлення затверджень мають відповідати номеру кроку в `TUTORIAL.md` з гілки `main`. Наприклад, затвердження з повідомленням `10.1` буде завантажено тоді, коли користувач перейде до кроку `10.1`.

Щоб внести зміни до затверджень на гілці версії, потрібно перебазувати та відредагувати ті затвердження, які хочете змінити. Це перепише історію Git, тому ми не можемо приймати PR до гілок цього типу. Гілку версії не можна змінювати, як тільки вона з’явиться на репозиторії freeCodeCamp.

> [!WARNING]
> 
> Ніколи не вносьте чи затверджуйте зміни до гілки версії, яка розташована на одному з репозиторіїв freeCodeCamp. Завжди створюйте нову

## Як зробити внесок

### Передумови

Встановіть [інструменти CodeRoad CLI](https://www.npmjs.com/package/@coderoad/cli) за допомогою `npm install -g @coderoad/cli`.

З останньою версією виникали деякі проблеми. Якщо `coderoad --version` не працює після налаштування, перейдіть на версію `0.7.0` за допомогою `npm install -g @coderoad/cli@0.7.0`.

### Робота на `main`

Ці інструкції призначені для PR, які вносять незначні зміни на `main` до **наявних уроків**. Зазвичай це друкарські й граматичні помилки, підказки, інструкції та виправлення у файлі `TUTORIAL.md`.

Для всього іншого, включно з додаванням чи видаленням уроків, див. [інструкцію з роботи над гілкою версії](#working-on-version-branch). Вам не потрібно створювати нову гілку версії — просто створіть PR, дотримуючись інструкцій нижче.

> [!NOTE]
> 
> Ці зміни використовуватимуть наявну гілку версії. Якщо це значні зміни, їх можна додати до `CHANGELOG.md`. У більшості випадків достатньо хорошого повідомлення затвердження

Ніколи не змінюйте файл `tutorial.json` напряму. Це виконується за допомогою інструментів CLI.

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

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

- Створіть копію останньої гілки версії за допомогою `git branch vX.X.X upstream/vX.X.X`. Цю гілку не потрібно перевіряти, вона має існувати.
- Створіть та перевірте нову гілку від `main`
- Внесіть **та затвердьте** зміни. Нагадування: нічого не змінюйте у файлі `tutorial.json`. Найімовірніше, вам потрібно внести зміни лише до `TUTORIAL.md`
- Запустіть `coderoad build`, щоб повторно створити файл `tutorial.json`
- Затвердьте зміни з `update json` як повідомленням
- Створіть PR

### Тестування змін на `main`

Якщо після інструкцій вище ви хочете перевірити зміни, внесені до `main`, дотримуйтесь цього:

- Виконайте інструкції з [репозиторію rdb-alpha](https://github.com/freeCodeCamp/rdb-alpha), щоб запустити контейнер
- Запустіть матеріал, використовуючи файл `tutorial.json` на новій гілці

### Перевірка PR до `main`

Якщо ви переглядаєте PR, який містить граматичні чи інструкційні зміни до `main`, як описано вище, зміни у `TUTORIAL.md` мають відповідати змінам у `tutorial.json`.

Файл `tutorial.json` не повинен містити змін хешів затвердження чи ідентифікаторів кроків/рівнів. Також не варто змінювати команди запуску/рівня або наглядачів за файлами. Бувають винятки, якщо наявні проблеми з кроком, але до них потрібно ставитись обережно.

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

### Робота над гілкою версії

> [!WARNING]
> 
> Нагадування: ніколи не вносьте чи затверджуйте зміни до гілки версії, яка розташована на одному з репозиторіїв freeCodeCamp. Завжди створюйте нову

Ви не зможете побачити зміни між гілками версій, оскільки історія Git буде переписана. Ретельно розглядайте та тестуйте нові гілки версій перед їх прийняттям для використання.

Ці інструкції призначені для змін на гілці версії, тобто тестів, тексту тестів, скидання файлів, додавання та видалення кроків тощо.

Дотримуйтесь цих інструкцій, щоб створити нову версію:

- Перевірте **останню** гілку версії за допомогою `git checkout -b vX.X.X upstream/vX.X.X`
- Створіть нову гілку від тієї, збільшивши версію за допомогою `git checkout -b vX.X.Y`
- Внесіть зміни до гілки версії. Для детальнішої інформації щодо роботи з матеріалами див. [документацію CodeRoad](https://coderoad.github.io/docs/edit-tutorial)
- Надішліть нову гілку до розгалуження за допомогою `git push -u origin vX.X.Y`
- Перевірте гілку `main`
- Створіть нову гілку від `main`. Наприклад, `feat/version-X.X.Y`
- Змініть `uri` у `coderoad.yaml` на своє розгалуження репозиторію. Таким чином ви та рецензент зможете провести тестування перед тим, як надіслати зміни до репозиторію freeCodeCamp. Змініть версію на нову гілку у двох місцях цього файлу. Додайте зміни нової версії до `CHANGELOG.md`. Внесіть будь-які інші потрібні зміни.
- Затвердьте зміни за допомогою повідомлення `feat: release version X.X.Y - <optional description>`
- Запустіть `coderoad build`, щоб створити новий файл `tutorial.json`
- Додайте та затвердьте файл
- Надішліть зміни до розгалуження
- Протестуйте зміни, дотримуючись [інструкцій нижче](#testing-changes-to-a-version-branch). Внесіть нові зміни та затвердьте їх так само, або, якщо ви задоволені, дотримуйтесь решти інструкцій
- Створіть PR до `main`, використовуючи нову гілку `feat/version-X.X.Y`. Назвіть його `version X.X.Y ready for review`. Його не буде об’єднано, але таким чином рецензенти знатимуть про готову нову версію
- Залиште решту для рецензентів

### Тестування змін на гілці версії

- Виконайте інструкції з [репозиторію rdb-alpha](https://github.com/freeCodeCamp/rdb-alpha), щоб запустити контейнер
- Запустіть матеріал, використовуючи файл `tutorial.json` на розгалуженні зі змінами. Переконайтесь, що використовуєте файл на гілці `feat: version-X.X.Y`, а не `main`

### Надсилання нової версії

Перед надсиланням нової версії перегляньте нову гілку `feat/version-vX.X.Y` (буде об’єднана до `main`) на розгалуженні користувача. Переконайтесь, що у файлі `CHANGELOG.md` є додатки, які містять нові зміни, та версія у двох місцях `coderoad.yaml` відповідає новій гілці версії.

Якщо ви маєте письмовий доступ до репозиторію freeCodeCamp, підтвердили файли `CHANGELOG` та `coderoad.yaml`, протестували зміни, використовуючи інструкції вище, та хочете надіслати нову версію матеріалу:

> [!WARNING]
> 
> Нагадування: ніколи не вносьте чи затверджуйте зміни до гілки версії, яка розташована на одному з репозиторіїв freeCodeCamp. Завжди створюйте нову

- Якщо у вас немає віддаленого доступу до місця, де наявні нові зміни, створіть віддалений доступ до розгалуження користувача за допомогою `git remote add <users_fork>`
- Видаліть будь-які **локальні** гілки, назва яких збігається з новими гілками. Скоріш за все `vX.X.Y` або `feat/version-X.X.Y`
- Перевірте гілку нової версії за допомогою `git checkout -b vX.X.Y <remote>/vX.X.Y`
- Надішліть гілку нової версії до репозиторію freeCodeCamp за допомогою `git push -u upstream/vX.X.Y`. Вам потрібно надіслати нову гілку перед тим, як оновити `main` з новим файлом `tutorial.json`
- Перевірте гілку користувача, яка буде об’єднана до `main`, за допомогою `git checkout -b feat/version-X.X.Y <remote>/feat/version-X.X.Y`
- Змініть `uri` у `coderoad.yaml` на репозиторій freeCodeCamp
- Додайте та затвердьте зміни
- Запустіть `coderoad build`, щоб створити новий файл `tutorial.json`
- Додайте та затвердьте файл
- Надішліть зміни до розгалуження за допомогою `git push -u origin/feat/version-X.X.Y`
- Створіть PR до `main` на репозиторії freeCodeCamp
- Якщо ви задоволені, об’єднайте його або залиште й попросіть когось іншого перевірити
- Як тільки PR об’єднано, відкрийте матеріал, дотримуючись інструкцій з [репозиторію rdb-alpha](https://github.com/freeCodeCamp/rdb-alpha), щоб переконатись, що все завантажується правильно та ви можете пройти декілька кроків
- Якщо будь-який PR для цієї версії існує, закрийте його

### Як повернутися до попередньої версії

- Створіть нову гілку від останньої `main` за допомогою `git checkout -b revert/to-version-X.X.X`
- Скасуйте всі затвердження гілки до потрібної вам версії. Наприклад, у вас є такі затвердження:

```
fix: typo
release: version 1.0.1
fix: typo
release: version 1.0.0
```

Якщо ви хочете повернутись до v1.0.0, скасуйте всі затвердження від `release: version 1.0.1` та пізніше

- Створіть PR. Назвіть його `revert: to version X.X.X`
