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 backend)
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- Алт текст за слике ради приступачности  
171 
172### Организација фајлова
173 
174- Лекције нумерисане секвенцијално (1-getting-started-lessons, 2-js-basics, итд.)  
175- Свaki пројекат има `solution/` и често `start/` или `your-work/` директоријуме  
176- Слике се чувају у директоријумима лекција `images/`  
177- Преводи у структури `translations/{language-code}/`  
178 
179## Састављање и деплојмент
180 
181### Деплоyмент Quiz App-а (Azure Static Web Apps)
182 
183quiz-app је конфигурисан за деплоyмент на Azure Static Web Apps:
184 
185```bash
186cd quiz-app
187npm run build      # Креира фолдер dist/
188# Деплојује путем GitHub Actions workflow-а приликом пуша на 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 из докса
201```
202 
203### Docsify документација
204 
205```bash
206npm install -g docsify-cli    # Инсталирајте Docsify глобално
207docsify serve                 # Покрените на localhost:3000
208```
209 
210### Састављање специфично за пројекат
211 
212Свaki директоријум пројекта може имати свој процес састављања:  
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   - Исправите све грешке и упозорења  
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- Наведите бројеве issue-ја у опису PR-а ако је применљиво  
253 
254### Процес рецензије
255 
256- PR-ове рецензирају одржаваоци и заједница  
257- Приоритет је јасноћа едукације  
258- Примери кода треба да прате савремене најбоље праксе  
259- Преводи су рецензирани за тачност и културну прикладност  
260 
261## Систем превођења
262 
263### Аутоматски превод
264 
265- Користи GitHub Actions са co-op-translator workflow-ом  
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 верзија >=10  
303- Проверите да ли је порт већ у употреби  
304- Уверите се да су све зависности инсталиране помоћу `npm install`  
305 
306**Прегледачки екстензија се не учитава**:  
307- Проверите да ли је manifest.json правилно форматиран  
308- Погледајте конзолу прегледача због грешака  
309- Пратите упутства за инсталацију екстензије специфична за прегледач  
310 
311**Проблеми са Python чат пројектом**:  
312- Проверите да је OpenAI пакет инсталиран: `pip install openai`  
313- Верификујте да је GITHUB_TOKEN подешен као environment варијабла  
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### Environment варијабле
338 
339- API кључеви никада не смеју бити пуштени у репозиторијум  
340- Користите `.env` фајлове (већ имају `.gitignore`)  
341- Документујте потребне environment варијабле у README-јима пројеката  
342 
343### Python пројекти
344 
345- Користите virtual окружје: `python -m venv venv`  
346- Одржавајте зависности ажурним  
347- GitHub токени треба да имају минималне потребне дозволе  
348 
349### Приступ GitHub Models
350 
351- Потребни су Personal Access Tokens (PAT)  
352- Токени треба да се чувају као environment варијабле  
353- Никада не пуштајте токене или акредитиве у репозиторијум  
354 
355## Додатне напомене
356 
357### Циљна публика
358 
359- Потпуни почетници у веб развоју  
360- Студенти и самоуки  
361- Наставници који користе курикулум у учионицама  
362- Садржај је дизајниран за приступачност и постепено грађење вештина  
363 
364### Едукативна филозофија
365 
366- Приступ учењу заснован на пројектима  
367- Честа провера знања (квизови)  
368- Практичне вежбе кодирања  
369- Примери из стварног света  
370- Фокус на основе пре framework-a  
371 
372### Одржавање репозиторијума
373 
374- Активна заједница ученика и сарадника  
375- Редовна ажурирања зависности и садржаја  
376- Пратите проблеме и дискусије од стране одржавалаца  
377- Аутоматско ажурирање превода преко GitHub Actions  
378 
379### Повезани ресурси
380 
381- [Microsoft Learn модули](https://docs.microsoft.com/learn/)  
382- [Student Hub ресурси](https://docs.microsoft.com/learn/student-hub/)  
383- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) препоручен за ученике  
384- Додатни курсови: Генеративни AI, Наука о подацима, ML, IoT курикулуми  
385 
386### Рад са појединачним пројектима
387 
388За детаљна упутства о појединачним пројектима погледајте README фајлове у:  
389- `quiz-app/README.md` - Vue 3 квиз апликација  
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- Свaka лекција је самостална  
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 -->