# 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 ## Команди для налаштування Цей репозиторій призначений переважно для споживання навчального контенту. Для роботи з конкретними проєктами: ### Налаштування основного репозиторію ```bash git clone https://github.com/microsoft/Web-Dev-For-Beginners.git cd Web-Dev-For-Beginners ``` ### Налаштування додатку для вікторин (Vue 3 + Vite) ```bash cd quiz-app npm install npm run dev # Start development server npm run build # Build for production npm run lint # Run ESLint ``` ### API банківського проєкту (Node.js + Express) ```bash cd 7-bank-project/api npm install npm start # Start API server npm run lint # Run ESLint npm run format # Format with Prettier ``` ### Проєкти розширень для браузера ```bash cd 5-browser-extension/solution npm install # Follow browser-specific extension loading instructions ``` ### Проєкти космічної гри ```bash cd 6-space-game/solution npm install # Open index.html in browser or use Live Server ``` ### Проєкт чату (Python Backend) ```bash cd 9-chat-project/solution/backend/python pip install openai # Set GITHUB_TOKEN environment variable python api.py ``` ## Робочий процес розробки ### Для контрибуторів контенту 1. **Форкніть репозиторій** у свій обліковий запис GitHub 2. **Клонуйте форк** локально 3. **Створіть нову гілку** для своїх змін 4. Внесіть зміни до контенту уроків або прикладів коду 5. Протестуйте будь-які зміни коду у відповідних каталогах проєктів 6. Надішліть pull request відповідно до рекомендацій щодо внеску ### Для учнів 1. Форкніть або клонуйте репозиторій 2. Переміщайтеся по каталогах уроків послідовно 3. Читайте файли README для кожного уроку 4. Виконуйте вікторини перед уроком на https://ff-quizzes.netlify.app/web/ 5. Працюйте з прикладами коду в папках уроків 6. Виконуйте завдання та виклики 7. Проходьте вікторини після уроку ### Жива розробка - **Документація**: Запустіть `docsify serve` у кореневій папці (порт 3000) - **Додаток для вікторин**: Запустіть `npm run dev` у папці quiz-app - **Проєкти**: Використовуйте розширення Live Server у VS Code для HTML-проєктів - **API-проєкти**: Запустіть `npm start` у відповідних каталогах API ## Інструкції з тестування ### Тестування додатку для вікторин ```bash cd quiz-app npm run lint # Check for code style issues npm run build # Verify build succeeds ``` ### Тестування API банківського проєкту ```bash cd 7-bank-project/api npm run lint # Check for code style issues node server.js # Verify server starts without errors ``` ### Загальний підхід до тестування - Це навчальний репозиторій без комплексних автоматизованих тестів - Ручне тестування зосереджене на: - Виконанні прикладів коду без помилок - Коректній роботі посилань у документації - Успішному завершенні збірки проєктів - Дотриманні найкращих практик у прикладах ### Перевірки перед відправкою - Запустіть `npm run lint` у каталогах із package.json - Перевірте валідність посилань у markdown - Протестуйте приклади коду в браузері або Node.js - Переконайтеся, що переклади зберігають правильну структуру ## Рекомендації щодо стилю коду ### JavaScript - Використовуйте сучасний синтаксис ES6+ - Дотримуйтесь стандартних конфігурацій ESLint, наданих у проєктах - Використовуйте зрозумілі назви змінних і функцій для навчальної ясності - Додавайте коментарі, що пояснюють концепції для учнів - Форматуйте код за допомогою Prettier, якщо він налаштований ### HTML/CSS - Семантичні елементи HTML5 - Принципи адаптивного дизайну - Зрозумілі конвенції щодо назв класів - Коментарі, що пояснюють техніки CSS для учнів ### Python - Дотримуйтесь стилю PEP 8 - Зрозумілі, навчальні приклади коду - Типізація там, де це корисно для навчання ### Документація Markdown - Чітка ієрархія заголовків - Блоки коду зі специфікацією мови - Посилання на додаткові ресурси - Знімки екрана та зображення в папках `images/` - Альтернативний текст для зображень для доступності ### Організація файлів - Уроки пронумеровані послідовно (1-getting-started-lessons, 2-js-basics тощо) - Кожен проєкт має папки `solution/` і часто `start/` або `your-work/` - Зображення зберігаються в папках `images/`, специфічних для уроків - Переклади в структурі `translations/{language-code}/` ## Збірка та розгортання ### Розгортання додатку для вікторин (Azure Static Web Apps) Додаток quiz-app налаштований для розгортання в Azure Static Web Apps: ```bash cd quiz-app npm run build # Creates dist/ folder # Deploys via GitHub Actions workflow on push to main ``` Конфігурація Azure Static Web Apps: - **Розташування додатку**: `/quiz-app` - **Розташування вихідних файлів**: `dist` - **Робочий процес**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml` ### Генерація документації у форматі PDF ```bash npm install # Install docsify-to-pdf npm run convert # Generate PDF from docs ``` ### Документація Docsify ```bash npm install -g docsify-cli # Install Docsify globally docsify serve # Serve on localhost:3000 ``` ### Збірки, специфічні для проєктів Кожен каталог проєкту може мати власний процес збірки: - Проєкти на Vue: `npm run build` створює продакшн-бандли - Статичні проєкти: Немає етапу збірки, файли можна використовувати напряму ## Рекомендації щодо pull request ### Формат заголовків Використовуйте чіткі, описові заголовки, що вказують на область змін: - `[Quiz-app] Додати нову вікторину для уроку X` - `[Lesson-3] Виправити помилку в проєкті тераріуму` - `[Translation] Додати переклад уроку 5 іспанською` - `[Docs] Оновити інструкції з налаштування` ### Необхідні перевірки Перед відправкою PR: 1. **Якість коду**: - Запустіть `npm run lint` у відповідних каталогах проєктів - Виправте всі помилки та попередження lint 2. **Перевірка збірки**: - Запустіть `npm run build`, якщо це необхідно - Переконайтеся, що немає помилок збірки 3. **Перевірка посилань**: - Протестуйте всі посилання в markdown - Переконайтеся, що посилання на зображення працюють 4. **Огляд контенту**: - Перевірте орфографію та граматику - Переконайтеся, що приклади коду правильні та навчальні - Перевірте, чи переклади зберігають оригінальний зміст ### Вимоги до внеску - Погодьтеся з Microsoft CLA (автоматична перевірка при першому PR) - Дотримуйтесь [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/) - Дивіться [CONTRIBUTING.md](./CONTRIBUTING.md) для детальних рекомендацій - Згадуйте номери проблем у описі PR, якщо це доречно ### Процес перегляду - PR переглядаються мейнтейнерами та спільнотою - Пріоритет надається навчальній ясності - Приклади коду повинні відповідати сучасним найкращим практикам - Переклади перевіряються на точність і культурну відповідність ## Система перекладу ### Автоматичний переклад - Використовує GitHub Actions із робочим процесом co-op-translator - Автоматично перекладає на 50+ мов - Вихідні файли в основних каталогах - Перекладені файли в `translations/{language-code}/` ### Додавання покращень до ручного перекладу 1. Знайдіть файл у `translations/{language-code}/` 2. Внесіть покращення, зберігаючи структуру 3. Переконайтеся, що приклади коду залишаються функціональними 4. Протестуйте будь-який локалізований контент вікторин ### Метадані перекладу Перекладені файли включають заголовок метаданих: ```markdown ``` ## Виправлення помилок і усунення несправностей ### Поширені проблеми **Додаток для вікторин не запускається**: - Перевірте версію 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 для узгодженого форматування - Використовуйте DevTools браузера для налагодження JavaScript - Для проєктів на Vue встановіть розширення Vue DevTools для браузера ### Міркування щодо продуктивності - Велика кількість перекладених файлів (50+ мов) означає, що повні клонування є великими - Використовуйте неглибоке клонування, якщо працюєте лише над контентом: `git clone --depth 1` - Виключайте переклади з пошуку, якщо працюєте над англійським контентом - Процеси збірки можуть бути повільними при першому запуску (npm install, Vite build) ## Міркування щодо безпеки ### Змінні середовища - API-ключі ніколи не повинні бути закомічені в репозиторій - Використовуйте `.env` файли (вже в `.gitignore`) - Документуйте необхідні змінні середовища в README проєктів ### Проєкти на Python - Використовуйте віртуальні середовища: `python -m venv venv` - Підтримуйте залежності в актуальному стані - Токени GitHub повинні мати мінімально необхідні дозволи ### Доступ до GitHub Models - Потрібні персональні токени доступу (PAT) для GitHub Models - Токени повинні зберігатися як змінні середовища - Ніколи не комітьте токени або облікові дані ## Додаткові примітки ### Цільова аудиторія - Повні новачки у веб-розробці - Студенти та самонавчальники - Викладачі, які використовують програму в класах - Контент розроблений для доступності та поступового нарощування навичок ### Освітня філософія - Підхід на основі проєктів - Часті перевірки знань (вікторини) - Практичні вправи з кодування - Приклади реального застосування - Фокус на основах перед переходом до фреймворків ### Підтримка репозиторію - Активна спільнота учнів і контрибуторів - Регулярні оновлення залежностей і контенту - Проблеми та обговорення контролюються мейнтейнерами - Оновлення перекладів автоматизовані через GitHub Actions ### Супутні ресурси - [Модулі Microsoft Learn](https://docs.microsoft.com/learn/) - [Ресурси Student Hub](https://docs.microsoft.com/learn/student-hub/) - [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=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](https://github.com/Azure/co-op-translator). Хоча ми прагнемо до точності, звертаємо вашу увагу, що автоматичні переклади можуть містити помилки або неточності. Оригінальний документ мовою оригіналу слід вважати авторитетним джерелом. Для критично важливої інформації рекомендується професійний переклад людиною. Ми не несемо відповідальності за будь-які непорозуміння або неправильне тлумачення, що виникли внаслідок використання цього перекладу.