# AGENTS.md ## Преглед на проекта Това е образователен репозиториум за обучение по основи на уеб разработката за начинаещи. Учебната програма е цялостен 12-седмичен курс, разработен от Microsoft Cloud Advocates, включващ 24 практически урока, обхващащи JavaScript, CSS и HTML. ### Основни компоненти - **Образователно съдържание**: 24 структурирани урока, организирани в модули, базирани на проекти - **Практически проекти**: Terrarium, Typing Game, Browser Extension, Space Game, Banking App, Code Editor и AI Chat Assistant - **Интерактивни тестове**: 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 на Bank проект (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 # Следвайте указанията за зареждане на разширения специфични за браузъра ``` ### Проекти за Space Game ```bash cd 6-space-game/solution npm install # Отворете index.html в браузър или използвайте Live Server ``` ### Chat проект (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 заявки, следвайки указанията за допринасяне ### За учащи се 1. Форкнете или клонирайте репозиториума 2. Навигирайте към директориите с уроци последователно 3. Прочетете README файловете за всеки урок 4. Завършете тестовете преди урока на https://ff-quizzes.netlify.app/web/ 5. Работете с примерите с код в папките на уроците 6. Попълнете задания и предизвикателства 7. Изпълнете тестове след урока ### Живо разработване - **Документация**: Стартирайте `docsify serve` в корена (порт 3000) - **Quiz App**: Стартирайте `npm run dev` в директорията quiz-app - **Проекти**: Използвайте разширението VS Code Live Server за 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/` - Алтернативен текст за изображенията за достъпност ### Организация на файловете - Уроците са номерирани последователно (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` - **Workflow**: `.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 заявки ### Формат на заглавието Използвайте ясни, описателни заглавия, указващи областта на промяната: - `[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 с 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 - Необходими са лични токени за достъп (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 quiz приложение - `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). Въпреки че се стремим към точност, моля, имайте предвид, че автоматизираните преводи могат да съдържат грешки или неточности. Оригиналният документ на неговия роден език трябва да се счита за авторитетен източник. За критична информация се препоръчва професионален човешки превод. Ние не носим отговорност за никакви недоразумения или неправилни тълкувания, произтичащи от използването на този превод.