# 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. **Fork-ујте репозиторијум** на свој GitHub налог 2. **Клонирајте свој fork** локално 3. **Креирајте нову грану** за своје измене 4. Направите измене у садржају лекција или примерима кода 5. Тестирајте измене кода у релевантним директоријумима пројеката 6. Поднесите pull захтеве у складу са смерницама за допринос ### За ученике 1. Fork-ујте или клонирајте репозиторијум 2. Прелазите кроз директоријуме лекција редом 3. Читајте README датотеке за сваку лекцију 4. Завршите квизове пре лекције на https://ff-quizzes.netlify.app/web/ 5. Радите на примерима кода у фасциклама лекција 6. Завршите задатке и изазове 7. Урадите квизове након лекције ### Развој уживо - **Документација**: Покрените `docsify serve` у корену (порт 3000) - **Апликација за квизове**: Покрените `npm run dev` у директоријуму quiz-app - **Пројекти**: Користите VS Code Live Server екстензију за 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/` - Alt текст за слике ради приступачности ### Организација датотека - Лекције нумерисане редом (1-getting-started-lessons, 2-js-basics, итд.) - Сваки пројекат има `solution/` и често `start/` или `your-work/` директоријуме - Слике смештене у директоријуме `images/` специфичне за лекцију - Преводи у структури `translations/{language-code}/` ## Изградња и распоређивање ### Распоређивање апликације за квизове (Azure Static Web Apps) Апликација за квизове је конфигурисана за распоређивање на 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` - **Workflow**: `.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 захтеве ### Формат наслова Користите јасне, описне наслове који указују на област измене: - `[Quiz-app] Add new quiz for lesson X` - `[Lesson-3] Fix typo in terrarium project` - `[Translation] Add Spanish translation for lesson 5` - `[Docs] Update setup instructions` ### Захтеване провере Пре подношења 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 workflow-ом - Аутоматски преводи на 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 - Personal Access Tokens (PAT) су потребни за GitHub Models - Токени треба да буду чувани као променљиве окружења - Никада не шаљите токене или креденцијале ## Додатне напомене ### Циљна публика - Потпуни почетници у веб развоју - Студенти и самоуки ученици - Наставници који користе курикулум у учионицама - Садржај је дизајниран за приступачност и постепено стицање вештина ### Образовна филозофија - Приступ учењу заснован на пројектима - Честа провера знања (квизови) - Практичне вежбе кодирања - Примери примене у стварном свету - Фокус на основама пре коришћења оквира ### Одржавање репозиторијума - Активна заједница ученика и доприносиоца - Редовна ажурирања зависности и садржаја - Проблеми и дискусије прати тим одржаваоца - Ажурирања превода аутоматизована преко GitHub Actions ### Повезани ресурси - [Microsoft Learn модули](https://docs.microsoft.com/learn/) - [Ресурси за студенте](https://docs.microsoft.com/learn/student-hub/) - [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) препоручен за ученике - Додатни курсеви: Генеративни AI, наука о подацима, 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). Иако се трудимо да обезбедимо тачност, молимо вас да имате у виду да аутоматски преводи могу садржати грешке или нетачности. Оригинални документ на његовом изворном језику треба сматрати меродавним извором. За критичне информације препоручује се професионални превод од стране људи. Не преузимамо одговорност за било каква погрешна тумачења или неспоразуме који могу настати услед коришћења овог превода.