AGENTS.md

1# AGENTS.md
2 
3## Огляд проєкту
4 
5Це навчальний репозиторій курсу для викладання основ веб-розробки для початківців. Курс є всебічним 12-тижневим курсом, розробленим Microsoft Cloud Advocates, що включає 24 практичні уроки з JavaScript, CSS та HTML.
6 
7### Ключові компоненти
8 
9- **Навчальний контент**: 24 структуровані уроки, організовані в модулі, орієнтовані на проєкти
10- **Практичні проєкти**: Терраріум, Гра на друку, Розширення браузера, Космічна гра, Банківський додаток, Код-редактор і AI чат-асистент
11- **Інтерактивні вікторини**: 48 вікторин по 3 питання у кожній (до/після уроку)
12- **Підтримка багатьох мов**: Автоматичний переклад більш ніж на 50 мов за допомогою GitHub Actions
13- **Технології**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (для AI проєктів)
14 
15### Архітектура
16 
17- Репозиторій з навчальним контентом, структурованим за уроками
18- Кожна директорія уроку містить README, приклади коду та рішення
19- Окремі проєкти розміщені в власних папках (quiz-app, різні уроки)
20- Система перекладів з використанням GitHub Actions (co-op-translator)
21- Документація подається через Docsify і доступна у форматі PDF
22 
23## Команди для налаштування
24 
25Цей репозиторій призначений переважно для споживання навчального контенту. Для роботи з конкретними проєктами:
26 
27### Основне налаштування репозиторію
28 
29```bash
30git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
31cd Web-Dev-For-Beginners
32```
33 
34### Налаштування Quiz App (Vue 3 + Vite)
35 
36```bash
37cd quiz-app
38npm install
39npm run dev        # Запустити сервер розробки
40npm run build      # Зібрати для продакшена
41npm run lint       # Запустити ESLint
42```
43 
44### API Банківського проєкту (Node.js + Express)
45 
46```bash
47cd 7-bank-project/api
48npm install
49npm start          # Запустити сервер API
50npm run lint       # Запустити ESLint
51npm run format     # Відформатувати за допомогою Prettier
52```
53 
54### Проєкти розширень браузера
55 
56```bash
57cd 5-browser-extension/solution
58npm install
59# Дотримуйтесь інструкцій із завантаження розширень, специфічних для браузера
60```
61 
62### Проєкти космічної гри
63 
64```bash
65cd 6-space-game/solution
66npm install
67# Відкрийте index.html у браузері або використовуйте Live Server
68```
69 
70### Проєкт чату (Python бекенд)
71 
72```bash
73cd 9-chat-project/solution/backend/python
74pip install openai
75# Встановіть змінну середовища GITHUB_TOKEN
76python api.py
77```
78 
79## Робочий процес розробки
80 
81### Для внесення контенту
82 
831. **Форкніть репозиторій** у свій акаунт GitHub
842. **Клонуйте ваш форк** локально
853. **Створіть нову гілку** для своїх змін
864. Внесіть зміни у контент уроків або приклади коду
875. Перевірте коди у відповідних директоріях проєктів
886. Надішліть pull request відповідно до інструкцій внесення змін
89 
90### Для учнів
91 
921. Форкніть або клонувати репозиторій
932. Перейдіть послідовно до директорій уроків
943. Читайте README в кожному уроці
954. Проходьте вікторини перед уроком на https://ff-quizzes.netlify.app/web/
965. Працюйте з прикладами коду в папках уроків
976. Виконуйте завдання і виклики
987. Проходьте вікторини після уроку
99 
100### Жива розробка
101 
102- **Документація**: Запустіть `docsify serve` у корені (порт 3000)
103- **Quiz App**: Запустіть `npm run dev` у директорії quiz-app
104- **Проєкти**: Використовуйте розширення VS Code Live Server для HTML-проєктів
105- **API проєкти**: Запустіть `npm start` у відповідних API директоріях
106 
107## Інструкції для тестування
108 
109### Тестування Quiz App
110 
111```bash
112cd quiz-app
113npm run lint       # Перевірте проблеми зі стилем коду
114npm run build      # Переконайтеся, що збірка проходить успішно
115```
116 
117### Тестування Bank API
118 
119```bash
120cd 7-bank-project/api
121npm run lint       # Перевірте наявність проблем зі стилем коду
122node server.js     # Переконайтеся, що сервер запускається без помилок
123```
124 
125### Загальний підхід до тестування
126 
127- Це навчальний репозиторій без комплексних автоматизованих тестів
128- Ручне тестування орієнтоване на:
129  - Запуск прикладів коду без помилок
130  - Правильну роботу посилань у документації
131  - Успішне збирання проєктів
132  - Відповідність прикладів найкращим практикам
133 
134### Перевірка перед подачею
135 
136- Запустіть `npm run lint` у директоріях з package.json
137- Перевірте валідність markdown посилань
138- Тестуйте приклади коду у браузері або Node.js
139- Перевірте, що переклади мають правильну структуру
140 
141## Керівництво по стилю коду
142 
143### JavaScript
144 
145- Використовуйте сучасний синтаксис ES6+
146- Дотримуйтесь стандартних ESLint конфігурацій проектів
147- Використовуйте зрозумілі імена змінних і функцій для навчальної ясності
148- Додавайте коментарі, що пояснюють концепції для учнів
149- Форматуйте код за допомогою Prettier, де налаштовано
150 
151### HTML/CSS
152 
153- Семантичні елементи HTML5
154- Принципи адаптивного дизайну
155- Чітка система імен класів
156- Коментарі, що пояснюють CSS-техніки для учнів
157 
158### Python
159 
160- Дотримання стилю PEP 8
161- Зрозумілі, навчальні приклади коду
162- Використання типових підказок, якщо це допомагає навчанню
163 
164### Документація у Markdown
165 
166- Чітка ієрархія заголовків
167- Код-блоки з вказанням мови
168- Посилання на додаткові ресурси
169- Скриншоти та зображення в папках `images/`
170- Опис alt для зображень для доступності
171 
172### Організація файлів
173 
174- Уроки пронумеровані послідовно (1-getting-started-lessons, 2-js-basics тощо)
175- Кожен проєкт має папки `solution/` та часто `start/` або `your-work/`
176- Зображення зберігаються у папках уроків `images/`
177- Переклади зберігаються у структурі `translations/{language-code}/`
178 
179## Збирання та розгортання
180 
181### Розгортання Quiz App (Azure Static Web Apps)
182 
183quiz-app налаштовано для розгортання Azure Static Web Apps:
184 
185```bash
186cd quiz-app
187npm run build      # Створює папку dist/
188# Виконує розгортання через workflow GitHub Actions при пуші в main
189```
190 
191Конфігурація Azure Static Web Apps:
192- **Розташування додатку**: `/quiz-app`
193- **Розташування результату**: `dist`
194- **Workflow**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`
195 
196### Генерація PDF документації
197 
198```bash
199npm install                    # Встановіть docsify-to-pdf
200npm run convert               # Згенерувати PDF з docs
201```
202 
203### Документація Docsify
204 
205```bash
206npm install -g docsify-cli    # Встановіть Docsify глобально
207docsify serve                 # Запуск на localhost:3000
208```
209 
210### Зборки для конкретних проєктів
211 
212Кожна директорія проєкту може мати власний процес збірки:
213- Vue проєкти: `npm run build` створює продакшн-бандли
214- Статичні проєкти: Кроку збірки немає, файли подаються напряму
215 
216## Керівництво з Pull Request
217 
218### Формат заголовку
219 
220Використовуйте чіткі, описові заголовки, що вказують область змін:
221- `[Quiz-app] Додати нову вікторину для уроку X`
222- `[Lesson-3] Виправити описку у проєкті терраріум`
223- `[Translation] Додати іспанський переклад для уроку 5`
224- `[Docs] Оновити інструкції з налаштування`
225 
226### Обов’язкові перевірки
227 
228Перед подачею PR:
229 
2301. **Якість коду**:
231   - Запустіть `npm run lint` у відповідних директоріях проєктів
232   - Виправте всі помилки і зауваження lint
233 
2342. **Перевірка збірки**:
235   - Запустіть `npm run build`, якщо застосовно
236   - Переконайтесь, що немає помилок збірки
237 
2383. **Перевірка посилань**:
239   - Протестуйте всі markdown-посилання
240   - Перевірте роботу зображень
241 
2424. **Перевірка контенту**:
243   - Вичитка на орфографію та граматику
244   - Переконайтесь, що приклади коду коректні і навчальні
245   - Перевірте, що переклади зберігають оригінальний зміст
246 
247### Вимоги до внесення змін
248 
249- Погодьтеся з Microsoft CLA (автоматична перевірка при першому PR)
250- Дотримуйтесь [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/)
251- Див. [CONTRIBUTING.md](./CONTRIBUTING.md) для детальних інструкцій
252- Вказуйте номери issues у описі PR, якщо застосовно
253 
254### Процес огляду
255 
256- PR перевіряють мейнтейнери і спільнота
257- Пріоритет надається навчальній зрозумілості
258- Приклади коду мають відповідати сучасним кращим практикам
259- Переклади перевіряються на точність і культурну відповідність
260 
261## Система перекладів
262 
263### Автоматичний переклад
264 
265- Використовує GitHub Actions з workflow co-op-translator
266- Автоматично перекладає на понад 50 мов
267- Файли-джерела у головних директоріях
268- Переклади у `translations/{language-code}/`
269 
270### Додавання ручних покращень
271 
2721. Знайдіть файл у `translations/{language-code}/`
2732. Внесіть покращення, зберігаючи структуру
2743. Переконайтесь, що приклади коду функціональні
2754. Протестуйте локалізований контент вікторин
276 
277### Метадані перекладів
278 
279Перекладені файли містять метадані у шапці:
280```markdown
281<!--
282CO_OP_TRANSLATOR_METADATA:
283{
284  "original_hash": "...",
285  "translation_date": "...",
286  "source_file": "...",
287  "language_code": "..."
288}
289-->
290```
291 
292## Відлагодження та усунення проблем
293 
294### Типові проблеми
295 
296**Quiz app не запускається**:
297- Перевірте версію Node.js (рекомендується v14+)
298- Видаліть `node_modules` і `package-lock.json`, запустіть `npm install` знову
299- Перевірте конфлікти портів (за замовчуванням Vite використовує порт 5173)
300 
301**API сервер не запускається**:
302- Перевірте версію Node.js (node >=10)
303- Перевірте, чи порт не зайнятий
304- Переконайтесь, що всі залежності встановлені (`npm install`)
305 
306**Розширення браузера не завантажується**:
307- Перевірте формат manifest.json
308- Перегляньте помилки у консолі браузера
309- Дотримуйтесь інструкцій установки для конкретного браузера
310 
311**Проблеми з Python чат-проєктом**:
312- Переконайтесь, що пакет OpenAI встановлений: `pip install openai`
313- Перевірте наявність змінної середовища GITHUB_TOKEN
314- Перевірте права доступу GitHub Models
315 
316**Docsify не подає документацію**:
317- Встановіть docsify-cli глобально: `npm install -g docsify-cli`
318- Запустіть із кореневої папки репозиторію
319- Переконайтесь, що існує файл `docs/_sidebar.md`
320 
321### Поради щодо середовища розробки
322 
323- Використовуйте VS Code з розширенням Live Server для HTML-проєктів
324- Встановіть розширення ESLint і Prettier для консистентного форматування
325- Використовуйте DevTools браузера для відлагодження JavaScript
326- Для Vue проектів встановіть Vue DevTools браузерне розширення
327 
328### Особливості продуктивності
329 
330- Велика кількість перекладів (50+ мов) призводить до великих повних клонів
331- Використовуйте shallow clone, якщо працюєте тільки з контентом: `git clone --depth 1`
332- Ігноруйте переклади в пошуку при роботі з англійським контентом
333- Процеси збірки можуть бути повільними при першому запуску (npm install, Vite build)
334 
335## Заходи безпеки
336 
337### Змінні оточення
338 
339- API ключі ніколи не мають потрапляти у репозиторій
340- Використовуйте `.env` файли (вже в `.gitignore`)
341- Документуйте потрібні змінні в README проєктів
342 
343### Python проєкти
344 
345- Використовуйте віртуальні середовища: `python -m venv venv`
346- Оновлюйте залежності
347- Токени GitHub повинні мати мінімальні необхідні дозволи
348 
349### Доступ до GitHub Models
350 
351- Потрібні персональні токени доступу (PAT) для GitHub Models
352- Токени зберігайте у змінних оточення
353- Ніколи не комітьте токени чи облікові дані
354 
355## Додаткові відомості
356 
357### Цільова аудиторія
358 
359- Повні новачки у веб-розробці
360- Студенти та самонавчання
361- Викладачі, що використовують курс у класах
362- Контент створено з орієнтацією на доступність і поступове нарощування навичок
363 
364### Освітня філософія
365 
366- Проєктно-орієнтоване навчання
367- Часті перевірки знань (вікторини)
368- Практичні вправи з кодування
369- Приклади реальних застосувань
370- Фокус на основах перед фреймворками
371 
372### Підтримка репозиторію
373 
374- Активна спільнота учнів і контрибуторів
375- Регулярні оновлення залежностей і контенту
376- Моніторинг issues та дискусій мейнтейнерами
377- Автоматичні оновлення перекладів через GitHub Actions
378 
379### Пов’язані ресурси
380 
381- [Microsoft Learn modules](https://docs.microsoft.com/learn/)
382- [Student Hub resources](https://docs.microsoft.com/learn/student-hub/)
383- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) рекомендується для учнів
384- Додаткові курси: генеративний AI, Data Science, ML, IoT
385 
386### Робота з конкретними проєктами
387 
388Для детальних інструкцій з окремих проєктів дивіться README файли у:
389- `quiz-app/README.md` - Vue 3 quiz додаток
390- `7-bank-project/README.md` - Банківський додаток з автентифікацією
391- `5-browser-extension/README.md` - Розробка розширення браузера
392- `6-space-game/README.md` - Розробка гри на Canvas
393- `9-chat-project/README.md` - AI чат-асистент
394 
395### Структура монорепозиторію
396 
397Хоча це не традиційний монорепозиторій, він містить кілька незалежних проєктів:
398- Кожен урок автономний
399- Проєкти не ділять залежності
400- Можна працювати з окремими проєктами без впливу на інші
401- Клонування всього репозиторію для повного досвіду курсу
402 
403---
404 
405<!-- CO-OP TRANSLATOR DISCLAIMER START -->
406**Відмова від відповідальності**:  
407Цей документ був перекладений за допомогою сервісу автоматичного перекладу [Co-op Translator](https://github.com/Azure/co-op-translator). Хоча ми прагнемо до точності, будь ласка, майте на увазі, що автоматичні переклади можуть містити помилки або неточності. Оригінальний документ рідною мовою слід вважати авторитетним джерелом. Для критичної інформації рекомендується професійний переклад людиною. Ми не несемо відповідальності за будь-які непорозуміння або хибні тлумачення, що виникли внаслідок використання цього перекладу.
408<!-- CO-OP TRANSLATOR DISCLAIMER END -->