21 KiB

Raw Permalink Blame History Unescape Escape

AGENTS.md

Огляд проєкту

Це репозиторій навчальної програми для викладання основ веб-розробки для початківців. Програма — це комплексний 12-тижневий курс, розроблений Microsoft Cloud Advocates, що містить 24 практичні уроки, які охоплюють JavaScript, CSS та HTML.

Основні компоненти

Навчальний контент: 24 структуровані уроки, організовані в модулі на основі проєктів
Практичні проєкти: Терраріум, гра на друку, розширення браузера, космічна гра, банківський додаток, редактор коду та AI чат-асистент
Інтерактивні вікторини: 48 вікторин по 3 питання в кожній (оцінки до/після уроку)
Підтримка багатьох мов: Автоматизований переклад більш ніж 50 мовами за допомогою GitHub Actions
Технології: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (для AI проєктів)

Архітектура

Навчальний репозиторій зі структурою на основі уроків
Кожна папка уроку містить README, приклади коду та рішення
Окремі проєкти у різних директоріях (quiz-app, різні проєкти уроків)
Система перекладу з використанням GitHub Actions (co-op-translator)
Документація на Docsify і доступна в PDF

Команди для налаштування

Цей репозиторій призначений переважно для споживання навчального контенту. Для роботи з конкретними проєктами:

Основне налаштування репозиторію

git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
cd Web-Dev-For-Beginners

Налаштування Quiz App (Vue 3 + Vite)

cd quiz-app
npm install
npm run dev        # Запустити сервер розробки
npm run build      # Зібрати для продакшена
npm run lint       # Запустити ESLint

API банківського проєкту (Node.js + Express)

cd 7-bank-project/api
npm install
npm start          # Запустити API сервер
npm run lint       # Запустити ESLint
npm run format     # Відформатувати за допомогою Prettier

Проєкти розширень браузера

cd 5-browser-extension/solution
npm install
# Дотримуйтеся інструкцій завантаження розширень, специфічних для браузера

Проєкти космічної гри

cd 6-space-game/solution
npm install
# Відкрийте index.html у браузері або використайте Live Server

Чат-проєкт (бекенд на Python)

cd 9-chat-project/solution/backend/python
pip install openai
# Встановіть змінну середовища GITHUB_TOKEN
python api.py

Розробницький робочий процес

Для авторів контенту

Форкуйте репозиторій у свій обліковий запис GitHub
Клонуйте форк локально
Створіть нову гілку для своїх змін
Вносьте зміни до контенту уроків або прикладів коду
Тестуйте зміни коду у відповідних директоріях проєктів
Надсилайте pull request відповідно до правил внеску

Для учнів

Форкуйте або клоньте репозиторій
Послідовно переходьте в директорії уроків
Читайте README файли для кожного уроку
Виконуйте вікторини перед уроком на https://ff-quizzes.netlify.app/web/
Опрацьовуйте приклади коду в папках уроків
Виконуйте завдання та виклики
Вирішуйте вікторини після уроку

Живий розвиток

Документація: Запустіть docsify serve у корені (порт 3000)
Quiz App: Запустіть npm run dev у директорії quiz-app
Проєкти: Використовуйте розширення VS Code Live Server для HTML проєктів
API Проєкти: Запустіть npm start у відповідних директоріях API

Інструкції з тестування

Тестування Quiz App

cd quiz-app
npm run lint       # Перевірте проблеми зі стилем коду
npm run build      # Переконайтеся, що збірка проходить успішно

Тестування API банку

cd 7-bank-project/api
npm run lint       # Перевірте на наявність проблем зі стилем коду
node server.js     # Переконайтеся, що сервер запускається без помилок

Загальний підхід до тестування

Це навчальний репозиторій без повного автоматизованого тестування
Ручне тестування зосереджене на:
- запуску прикладів коду без помилок
- коректній роботі посилань у документації
- успішній збірці проєктів
- прикладах, що відповідають найкращим практикам

Перевірки перед відправкою

Запустіть npm run lint у директоріях з package.json
Перевірте коректність markdown-посилань
Тестуйте приклади коду в браузері або Node.js
Переконайтеся, що переклади зберігають правильну структуру

Керівництво зі стилю коду

JavaScript

Використовуйте сучасний синтаксис ES6+
Дотримуйтесь стандартних конфігурацій ESLint, що надаються в проєктах
Використовуйте змістовні назви змінних і функцій для навчальної ясності
Додавайте коментарі, що пояснюють концепції для учнів
Форматуйте код за допомогою Prettier, де налаштовано

HTML/CSS

Семантичні елементи HTML5
Принципи адаптивного дизайну
Чіткі найменування класів
Коментарі, що пояснюють CSS-техніки для учнів

Python

Керівництво за стилем PEP 8
Чіткі, навчальні приклади коду
Підказки типів, де корисно для навчання

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

Чітка ієрархія заголовків
Блоки коду з вказанням мови
Посилання на додаткові ресурси
Знімки екрану та зображення у папках images/
Атрибути alt для зображень для доступності

Організація файлів

Уроки пронумеровані послідовно (1-getting-started-lessons, 2-js-basics тощо)
Кожен проєкт має папки solution/ і часто start/ або your-work/
Зображення зберігаються у папках зображень конкретного уроку
Переклади у структурі translations/{language-code}/

Збірка і розгортання

Розгортання Quiz App (Azure Static Web Apps)

quiz-app налаштований для розгортання в Azure Static Web Apps:

cd quiz-app
npm run build      # Створює папку dist/
# Розгортає через GitHub Actions workflow при пуші в main

Конфігурація Azure Static Web Apps:

Розташування додатку: /quiz-app
Вихідне розташування: dist
Робочий процес: .github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml

Генерація PDF документації

npm install                    # Встановити docsify-to-pdf
npm run convert               # Згенерувати PDF з docs

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

npm install -g docsify-cli    # Встановити Docsify глобально
docsify serve                 # Запустити на localhost:3000

Збірка конкретних проєктів

Кожна директорія проєкту може мати власний процес збірки:

Проєкти на Vue: npm run build створює продакшн-бандли
Статичні проєкти: немає кроку збірки, файли подаються напряму

Інструкції для Pull Request

Формат заголовку

Використовуйте чіткі, описові заголовки, що вказують область змін:

[Quiz-app] Додати нову вікторину для уроку X
[Lesson-3] Виправити помилку в проєкті терраріуму
[Translation] Додати іспанський переклад для уроку 5
[Docs] Оновити інструкції з налаштування

Обов’язкові перевірки

Перед надсиланням PR:

Якість коду:
- Запустіть npm run lint у відповідних директоріях проєктів
- Виправте всі помилки та попередження лінтера
Перевірка збірки:
- Запустіть npm run build, якщо застосовується
- Переконайтеся, що немає помилок збірки
Перевірка посилань:
- Протестуйте всі markdown-посилання
- Переконайтеся, що посилання на зображення працюють
Перевірка контенту:
- Вичитайте на орфографічні та граматичні помилки
- Переконайтеся, що приклади коду коректні і навчальні
- Перевірте, що переклади зберегли оригінальний зміст

Вимоги до внеску

Погоджуйтесь з Microsoft CLA (автоматична перевірка при першому PR)
Дотримуйтеся Microsoft Open Source Code of Conduct
Див. CONTRIBUTING.md для детальних інструкцій
Посилайтеся на номери issue в описі PR, якщо це застосовується

Процес перегляду

PR переглядають підтримувачі та спільнота
Пріоритет надається освітній зрозумілості
Приклади коду повинні відповідати найкращим сучасним практикам
Переклади рецензуються на точність і культурну відповідність

Система перекладу

Автоматизований переклад

Використовує GitHub Actions з робочим процесом co-op-translator
Автоматичний переклад на понад 50 мов
Файли джерел у основних директоріях
Перекладені файли у папках translations/{language-code}/

Додавання вручну покращень перекладу

Знайдіть файл у translations/{language-code}/
Вносьте вдосконалення, зберігаючи структуру
Переконайтеся, що приклади коду залишаються працездатними
Тестуйте локалізований контент вікторин

Мета-дані перекладу

Перекладені файли містять заголовок з мета-даними:

<!--
CO_OP_TRANSLATOR_METADATA:
{
  "original_hash": "...",
  "translation_date": "...",
  "source_file": "...",
  "language_code": "..."
}
-->

Налагодження та усунення проблем

Поширені проблеми

Quiz app не запускається:

Перевірте версію Node.js (рекомендовано v14+)
Видаліть node_modules та package-lock.json, потім знову запустіть npm install
Перевірте конфлікти портів (за замовчуванням Vite використовує порт 5173)

API-сервер не стартує:

Переконайтеся, що версія Node.js відповідає мінімуму (node >=10)
Перевірте, чи порт не використовується
Впевніться, що всі залежності встановлені через npm install

Розширення браузера не завантажується:

Перевірте правильність форматування manifest.json
Перевірте консоль браузера на наявність помилок
Дотримуйтеся інструкцій з встановлення для конкретного браузера

Проблеми з чат-проєктом на Python:

Переконайтеся, що пакет OpenAI встановлений: pip install openai
Перевірте, що змінна середовища GITHUB_TOKEN встановлена
Переконайтеся у наявності дозволів на доступ до GitHub Models

Докси Docsify не запускаються:

Встановіть docsify-cli глобально: npm install -g docsify-cli
Запускайте з кореневого каталогу репозиторію
Переконайтеся, що існує файл docs/_sidebar.md

Поради для розробки

Використовуйте VS Code з розширенням Live Server для HTML проєктів
Встановіть розширення ESLint і Prettier для послідовного форматування
Використовуйте інструменти розробника браузера для налагодження JavaScript
Для Vue проєктів встановіть браузерне розширення Vue DevTools

Продуктивність

Велика кількість перекладених файлів (50+ мов) означає великий повний клон
Використовуйте shallow clone, якщо працюєте лише з контентом: git clone --depth 1
Виключайте переклади з пошуку при роботі з англійським контентом
Процеси збірки можуть бути повільними під час першого запуску (npm install, збірка Vite)

Міркування щодо безпеки

Змінні середовища

Ключі API ніколи не повинні зберігатися в репозиторії
Використовуйте файли .env (вже додані до .gitignore)
Зазначайте необхідні змінні середовища у README проєктів

Python проєкти

Використовуйте віртуальні середовища: python -m venv venv
Підтримуйте залежності актуальними
Токени GitHub повинні мати мінімально необхідні дозволи

Доступ до GitHub Models

Потрібні Personal Access Tokens (PAT) для GitHub Models
Токени слід зберігати як змінні середовища
Ніколи не комітьте токени або облікові дані

Додаткові нотатки

Цільова аудиторія

Повні початківці у веб-розробці
Студенти та самонавчальні
Викладачі, які використовують програму у класах
Контент розроблений для доступності та поступового розвитку навичок

Освітня філософія

Навчання через проєкти
Часті перевірки знань (вікторини)
Практичні вправи з кодування
Приклади застосування у реальному світі
Фокус на основах перед фреймворками

Підтримка репозиторію

Активна спільнота учнів і авторів
Регулярні оновлення залежностей та контенту
Підтримка і обговорення від кураторів
Автоматичне оновлення перекладів за допомогою GitHub Actions

Пов’язані ресурси

Microsoft Learn модулі
Студентський центр ресурсів
GitHub Copilot рекомендований для учнів
Додаткові курси: Генеративний AI, Data Science, ML, IoT навчальні курси

Робота з конкретними проєктами

Для докладних інструкцій щодо окремих проєктів дивіться README файли у:

quiz-app/README.md - Vue 3 додаток для вікторин
7-bank-project/README.md - Банківський додаток з аутентифікацією
5-browser-extension/README.md - Розробка розширень браузера
6-space-game/README.md - Розробка гри на Canvas
9-chat-project/README.md - Проєкт AI чат-асистента

Структура монорепозиторію

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

Кожен урок автономний
Проєкти не ділять залежностей
Працюйте над окремими проєктами без впливу на інші
Клонуйте весь репозиторій для повного досвіду навчальної програми

Відмова від відповідальності: Цей документ було перекладено за допомогою сервісу автоматичного перекладу Co-op Translator. Хоча ми прагнемо до точності, будь ласка, майте на увазі, що автоматизовані переклади можуть містити помилки або неточності. Оригінальний документ рідною мовою слід вважати авторитетним джерелом. Для критичної інформації рекомендується професійний людський переклад. Ми не несемо відповідальності за будь-які непорозуміння або помилкові тлумачення, що виникли через використання цього перекладу.

21 KiB Raw Permalink Blame History Unescape Escape