# 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 - **Пројекти**: Користите 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, итд.) - Свaki пројекат има `solution/` и често `start/` или `your-work/` директоријуме - Слике се чувају у директоријумима лекција `images/` - Преводи у структури `translations/{language-code}/` ## Састављање и деплојмент ### Деплоyмент Quiz App-а (Azure Static Web Apps) quiz-app је конфигурисан за деплоyмент на Azure Static Web Apps: ```bash cd quiz-app npm run build # Креира фолдер dist/ # Деплојује путем GitHub Actions workflow-а приликом пуша на 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 из докса ``` ### Docsify документација ```bash npm install -g docsify-cli # Инсталирајте Docsify глобално docsify serve # Покрените на localhost:3000 ``` ### Састављање специфично за пројекат Свaki директоријум пројекта може имати свој процес састављања: - 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) за детаљна упутства - Наведите бројеве issue-ја у опису PR-а ако је применљиво ### Процес рецензије - PR-ове рецензирају одржаваоци и заједница - Приоритет је јасноћа едукације - Примери кода треба да прате савремене најбоље праксе - Преводи су рецензирани за тачност и културну прикладност ## Систем превођења ### Аутоматски превод - Користи GitHub Actions са co-op-translator workflow-ом - Аутоматски преводи на више од 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 верзија >=10 - Проверите да ли је порт већ у употреби - Уверите се да су све зависности инсталиране помоћу `npm install` **Прегледачки екстензија се не учитава**: - Проверите да ли је manifest.json правилно форматиран - Погледајте конзолу прегледача због грешака - Пратите упутства за инсталацију екстензије специфична за прегледач **Проблеми са Python чат пројектом**: - Проверите да је OpenAI пакет инсталиран: `pip install openai` - Верификујте да је GITHUB_TOKEN подешен као environment варијабла - Проверите приступе 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) ## Безбедносне напомене ### Environment варијабле - API кључеви никада не смеју бити пуштени у репозиторијум - Користите `.env` фајлове (већ имају `.gitignore`) - Документујте потребне environment варијабле у README-јима пројеката ### Python пројекти - Користите virtual окружје: `python -m venv venv` - Одржавајте зависности ажурним - GitHub токени треба да имају минималне потребне дозволе ### Приступ GitHub Models - Потребни су Personal Access Tokens (PAT) - Токени треба да се чувају као environment варијабле - Никада не пуштајте токене или акредитиве у репозиторијум ## Додатне напомене ### Циљна публика - Потпуни почетници у веб развоју - Студенти и самоуки - Наставници који користе курикулум у учионицама - Садржај је дизајниран за приступачност и постепено грађење вештина ### Едукативна филозофија - Приступ учењу заснован на пројектима - Честа провера знања (квизови) - Практичне вежбе кодирања - Примери из стварног света - Фокус на основе пре framework-a ### Одржавање репозиторијума - Активна заједница ученика и сарадника - Редовна ажурирања зависности и садржаја - Пратите проблеме и дискусије од стране одржавалаца - Аутоматско ажурирање превода преко 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, Наука о подацима, 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 асистент за ћаскање ### Структура монорепозиторијума Иако није традиционални монорепозиторијум, овај репозиторијум садржи више независних пројеката: - Свaka лекција је самостална - Пројекти не деле зависности - Радите на појединачним пројектима без утицаја на остале - Клонирајте цео репозиторијум за пуну курикулумску комплетност --- **Одрицање од одговорности**: Овај документ је преведен коришћењем услуге за машински превод [Co-op Translator](https://github.com/Azure/co-op-translator). Иако се трудимо да превод буде прецизан, молимо вас да имате у виду да аутоматски преводи могу садржати грешке или нетачности. Оригинални документ на његовом изворном језику треба сматрати ауторитетом. За критичне информације препоручује се професионални превод који изводи стручни преводилац. Нисмо одговорни за било какве неспоразуме или погрешне тумачења која могу настати коришћењем овог превода.