freeCodeCamp/docs/i18n/ukrainian/how-to-work-on-tutorials-that-use-coderoad.md

На цій сторінці описано, як зробити внесок до матеріалів та проєктів 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 за допомогою npm install -g @coderoad/cli.

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

Робота на main

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

Для всього іншого, включно з додаванням чи видаленням уроків, див. інструкцію з роботи над гілкою версії. Вам не потрібно створювати нову гілку версії — просто створіть 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, щоб запустити контейнер
• Запустіть матеріал, використовуючи файл 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
• Надішліть нову гілку до розгалуження за допомогою 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
• Додайте та затвердьте файл
• Надішліть зміни до розгалуження
• Протестуйте зміни, дотримуючись інструкцій нижче. Внесіть нові зміни та затвердьте їх так само, або, якщо ви задоволені, дотримуйтесь решти інструкцій
• Створіть PR до main, використовуючи нову гілку feat/version-X.X.Y. Назвіть його version X.X.Y ready for review. Його не буде об’єднано, але таким чином рецензенти знатимуть про готову нову версію
• Залиште решту для рецензентів

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

• Виконайте інструкції з репозиторію 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, щоб переконатись, що все завантажується правильно та ви можете пройти декілька кроків
• Якщо будь-який 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