# 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 ``` ### Настройка на Quiz App (Vue 3 + Vite) ```bash cd quiz-app npm install npm run dev # Стартиране на сървър за разработка npm run build # Създаване за продукция npm run lint # Стартиране на ESLint ``` ### API на банковия проект (Node.js + Express) ```bash cd 7-bank-project/api npm install npm start # Стартиране на API сървър npm run lint # Стартиране на ESLint npm run format # Форматиране с Prettier ``` ### Проекти за разширения за браузър ```bash cd 5-browser-extension/solution npm install # Следвайте указанията за зареждане на разширения специфични за браузъра ``` ### Проекти за Космическата игра ```bash cd 6-space-game/solution npm install # Отворете index.html в браузър или използвайте Live Server ``` ### Проект за чат (Python backend) ```bash cd 9-chat-project/solution/backend/python pip install openai # Задаване на променливата на средата GITHUB_TOKEN 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) - **Quiz App**: Стартирайте `npm run dev` в директорията quiz-app - **Проекти**: Използвайте разширението Live Server на VS Code за HTML проекти - **API проекти**: Стартирайте `npm start` в съответните API директории ## Инструкции за тестване ### Тестване на Quiz App ```bash cd quiz-app npm run lint # Проверка за проблеми със стила на кода npm run build # Проверете дали сглобяването е успешно ``` ### Тестване на Bank API ```bash 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/` - Изображенията се съхраняват в папки `images/`, специфични за урока - Преводите са в структура `translations/{language-code}/` ## Създаване и внедряване ### Внедряване на Quiz App (Azure Static Web Apps) quiz-app е конфигуриран за внедряване в Azure Static Web Apps: ```bash cd quiz-app npm run build # Създава папка dist/ # Разгръща чрез GitHub Actions workflow при push към main ``` Конфигурация за Azure Static Web Apps: - **Папка на приложението**: `/quiz-app` - **Изходна папка**: `dist` - **Работен процес**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml` ### Генериране на документация в PDF ```bash npm install # Инсталиране на docsify-to-pdf npm run convert # Генериране на PDF от docs ``` ### Документация с Docsify ```bash 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: 1. **Качество на кода**: - Стартирайте `npm run 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 с workflow co-op-translator - Превежда автоматично на 50+ езика - Изходни файлове в основните директории - Преведените файлове в директории `translations/{language-code}/` ### Добавяне на ръчни подобрения на превода 1. Намерете файла в `translations/{language-code}/` 2. Направете подобрения, като запазите структурата 3. Уверете се, че примерите за код остават функционални 4. Тествайте локализираното съдържание на тестове ### Метаданни на превода Преведените файлове включват метаданни в хедъра: ```markdown ``` ## Отстраняване на грешки и проблеми ### Чести проблеми **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 за консистентно форматиране - Използвайте DevTools на браузъра за дебъгване на JavaScript - За Vue проекти инсталирайте Vue DevTools разширението за браузър ### Съображения за производителността - Голям брой преведени файлове (50+ езика) означава, че пълните клонирания са големи - Използвайте shallow clone, ако работите само със съдържание: `git clone --depth 1` - Изключвайте преводите от търсения при работа с английско съдържание - Процесите на билд могат да са бавни при първо изпълнение (npm install, Vite build) ## Съображения за сигурността ### Променливи на средата - API ключове никога не трябва да се комитират в хранилището - Използвайте `.env` файлове (вече в `.gitignore`) - Документирайте изискваните променливи на средата в README файловете на проектите ### Python проекти - Използвайте виртуални среди: `python -m venv venv` - Поддържайте зависимостите актуални - GitHub токените трябва да имат минималните необходими разрешения ### Достъп до GitHub Models - За GitHub Models се изискват Personal Access Tokens (PAT) - Токените трябва да се съхраняват като променливи на средата - Никога не комитвайте токени или креденшъли ## Допълнителни бележки ### Целева аудитория - Напълно начинаещи в уеб разработката - Студенти и самоуки учащи - Учители, използващи учебната програма в класната стая - Съдържанието е проектирано за достъпност и постепенно усъвършенстване на уменията ### Образователна философия - Подход, базиран на проекти - Чести проверявания на знания (тестове) - Практически упражнения по кодиране - Примери за реални приложения - Фокус върху основите преди рамките ### Поддръжка на хранилището - Активна общност от учащи и сътрудници - Редовни актуализации на зависимости и съдържание - Мониторинг на проблеми и дискусии от страна на поддържащите - Автоматизирани актуализации на преводите чрез 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) препоръчван за учащи - Допълнителни курсове: Generative 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 асистент за чат ### Структура на монохранилището Въпреки че не е традиционно монохранилище, това хранилище съдържа множество независими проекти: - Всеки урок е самостоятелен - Проектите не споделят зависимости - Работете по отделни проекти, без да засягате други - Клонирайте цялото хранилище за пълното учебно преживяване --- **Отказ от отговорност**: Този документ е преведен чрез AI преводаческа услуга [Co-op Translator](https://github.com/Azure/co-op-translator). Въпреки че се стремим към точност, моля, имайте предвид, че автоматизираните преводи могат да съдържат грешки или неточности. Оригиналният документ на неговия роден език трябва да се счита за авторитетен източник. За критична информация се препоръчва професионален човешки превод. Ние не носим отговорност за каквито и да било недоразумения или неправилни тълкувания, произтичащи от използването на този превод.