AGENTS.md

1# AGENTS.md
2 
3## Pregled projekta
4 
5To je učni učni načrt za poučevanje osnov spletnega razvoja za začetnike. Učni načrt je obsežen 12-tedenski tečaj, ki so ga razvili Microsoft Cloud Advocates, in vsebuje 24 praktičnih lekcij o JavaScriptu, CSS in HTML.
6 
7### Ključne sestavine
8 
9- **Izobraževalna vsebina**: 24 strukturiranih lekcij, organiziranih v modulih na osnovi projektov
10- **Praktični projekti**: Terarij, Tipkovniška igra, Razširitev brskalnika, Vesoljska igra, Bančna aplikacija, Urejevalnik kode in AI klepetalni pomočnik
11- **Interaktivni kvizi**: 48 kvizov s 3 vprašanji vsak (pred in po lekciji)
12- **Podpora za več jezikov**: Avtomatizirani prevodi za več kot 50 jezikov preko GitHub Actions
13- **Tehnologije**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (za AI projekte)
14 
15### Arhitektura
16 
17- Učni skladišče z strukturo na osnovi lekcij
18- Vsaka mapa lekcije vsebuje README, primere kode in rešitve
19- Samostojni projekti v ločenih imenikih (quiz-app, različni lekcijski projekti)
20- Sistem za prevajanje z uporabo GitHub Actions (co-op-translator)
21- Dokumentacija, postrežena preko Docsify in dostopna kot PDF
22 
23## Ukazi za nastavitev
24 
25To skladišče je primarno namenjeno za uživanje izobraževalne vsebine. Za delo z določenimi projekti:
26 
27### Nastavitev glavnega skladišča
28 
29```bash
30git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
31cd Web-Dev-For-Beginners
32```
33 
34### Nastavitev Quiz App (Vue 3 + Vite)
35 
36```bash
37cd quiz-app
38npm install
39npm run dev        # Zaženi razvojni strežnik
40npm run build      # Zgradi za produkcijo
41npm run lint       # Zaženi ESLint
42```
43 
44### API projekta Banka (Node.js + Express)
45 
46```bash
47cd 7-bank-project/api
48npm install
49npm start          # Zaženi API strežnik
50npm run lint       # Zaženi ESLint
51npm run format     # Oblikuj s Prettierjem
52```
53 
54### Projekti razširitev brskalnika
55 
56```bash
57cd 5-browser-extension/solution
58npm install
59# Upoštevajte navodila za nalaganje razširitev, specifična za brskalnik
60```
61 
62### Projekti vesoljske igre
63 
64```bash
65cd 6-space-game/solution
66npm install
67# Odprite index.html v brskalniku ali uporabite Live Server
68```
69 
70### Projekt klepeta (Python Backend)
71 
72```bash
73cd 9-chat-project/solution/backend/python
74pip install openai
75# Nastavite okoljsko spremenljivko GITHUB_TOKEN
76python api.py
77```
78 
79## Razvojni potek dela
80 
81### Za prispevatele vsebine
82 
831. **Razvezi skladišče (fork)** v svoj GitHub račun
842. **Kloniraj svoj fork** lokalno
853. **Ustvari nov podal (branch)** za svoje spremembe
864. Naredi spremembe v vsebini lekcij ali primerih kode
875. Testiraj spremembe kode v ustreznih mapah projektov
886. Pošlji pull requeste v skladu z navodili za prispevanje
89 
90### Za učence
91 
921. Razvezi ali kloniraj skladišče
932. Pomakni se zaporedno skozi mape lekcij
943. Preberi README datoteke za vsako lekcijo
954. Reši predlečnične kvize na https://ff-quizzes.netlify.app/web/
965. Delaj skozi primere kode v mapah lekcij
976. Dokončaj naloge in izzive
987. Reši postlečnične kvize
99 
100### Živ razvoj
101 
102- **Dokumentacija**: Zaženi `docsify serve` v korenu projekta (port 3000)
103- **Quiz App**: Zaženi `npm run dev` v mapi quiz-app
104- **Projekti**: Uporabi razširitev VS Code Live Server za HTML projekte
105- **API projekti**: Zaženi `npm start` v ustreznih API mapah
106 
107## Navodila za testiranje
108 
109### Testiranje Quiz App
110 
111```bash
112cd quiz-app
113npm run lint       # Preveri težave s slogom kode
114npm run build      # Preveri, ali je gradnja uspešna
115```
116 
117### Testiranje Bank API
118 
119```bash
120cd 7-bank-project/api
121npm run lint       # Preveri težave s slogom kode
122node server.js     # Preveri, ali strežnik zažene brez napak
123```
124 
125### Splošni pristop k testiranju
126 
127- To je učni repozitorij brez celovitega avtomatskega testiranja
128- Ročno testiranje se osredotoča na:
129  - Primeri kode tečejo brez napak
130  - Povezave v dokumentaciji delujejo pravilno
131  - Projekti se uspešno zgradijo
132  - Primeri sledijo najboljšim praksam
133 
134### Preverjanje pred oddajo
135 
136- Zaženi `npm run lint` v mapah z datoteko package.json
137- Preveri veljavnost povezav v markdownu
138- Testiraj primere kode v brskalniku ali Node.js
139- Preveri, da prevodi ohranjajo pravilno strukturo
140 
141## Smernice za stil kode
142 
143### JavaScript
144 
145- Uporaba sodobne sintakse ES6+
146- Sledenje standardnim ESLint konfiguracijam, podanim v projektih
147- Uporaba pomenljivih imen spremenljivk in funkcij za lažje razumevanje
148- Dodajanje komentarjev za pojasnitev konceptov za učence
149- Formatiranje z uporabo Prettier kjer je konfigurirano
150 
151### HTML/CSS
152 
153- Semantični elementi HTML5
154- Principi odzivnega oblikovanja
155- Jasne konvencije poimenovanja razredov
156- Komentarji, ki pojasnjujejo CSS tehnike za učence
157 
158### Python
159 
160- Slediti smernicam sloga PEP 8
161- Jasni, izobraževalni primeri kode
162- Tipiziranje (type hints) kjer je koristno za učenje
163 
164### Dokumentacija v Markdownu
165 
166- Jasna hierarhija naslovov
167- Bloki kode z navedbo jezika
168- Povezave do dodatnih virov
169- Posnetki zaslona in slike v mapah `images/`
170- Alt besedilo za slike zaradi dostopnosti
171 
172### Organizacija datotek
173 
174- Lekcije označene zaporedno (1-getting-started-lessons, 2-js-basics itd.)
175- Vsak projekt ima mape `solution/` in pogosto `start/` ali `your-work/`
176- Slike so shranjene v lekcijsko specifičnih mapah `images/`
177- Prevodi v strukturi `translations/{jezikovna-koda}/`
178 
179## Sestavljanje in nameščanje
180 
181### Namestitev Quiz App (Azure Static Web Apps)
182 
183quiz-app je konfiguriran za nameščanje v Azure Static Web Apps:
184 
185```bash
186cd quiz-app
187npm run build      # Ustvari mapo dist/
188# Izvede namestitev prek GitHub Actions poteka ob potisku na main
189```
190 
191Konfiguracija Azure Static Web Apps:
192- **Lokacija aplikacije**: `/quiz-app`
193- **Izhodna lokacija**: `dist`
194- **Delovni tok**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`
195 
196### Generiranje PDF dokumentacije
197 
198```bash
199npm install                    # Namestite docsify-to-pdf
200npm run convert               # Ustvari PDF iz docs
201```
202 
203### Dokumentacija Docsify
204 
205```bash
206npm install -g docsify-cli    # Namestite Docsify globalno
207docsify serve                 # Strežnik na localhost:3000
208```
209 
210### Gradnje specifične za projekte
211 
212Vsaka mapa projekta lahko ima lasten postopek gradnje:
213- Vue projekti: `npm run build` ustvari produkcijske pakete
214- Statični projekti: brez koraka gradnje, postreže se datoteke neposredno
215 
216## Smernice za pull requeste
217 
218### Oblika naslova
219 
220Uporabi jasne, opisne naslove, ki označujejo področje spremembe:
221- `[Quiz-app] Dodaj nov kviz za lekcijo X`
222- `[Lesson-3] Popravi tipkarsko napako v projektu terarij`
223- `[Translation] Dodaj španski prevod za lekcijo 5`
224- `[Docs] Posodobi navodila za nastavitev`
225 
226### Zahtevani pregledi
227 
228Pred oddajo PR:
229 
2301. **Kakovost kode**:
231   - Zaženi `npm run lint` v prizadetih projektnih mapah
232   - Odpravi vse napake in opozorila linterja
233 
2342. **Preverjanje gradnje**:
235   - Zaženi `npm run build` če je potrebno
236   - Prepričaj se, da ni napak pri gradnji
237 
2383. **Preverjanje povezav**:
239   - Testiraj vse markdown povezave
240   - Preveri delovanje referenc slik
241 
2424. **Pregled vsebine**:
243   - Preveri pravopis in slovnico
244   - Zagotovi, da so primeri kode pravilni in poučni
245   - Preveri, da prevodi ohranjajo originalni pomen
246 
247### Zahteve za prispevanje
248 
249- Strinjanje z Microsoft CLA (avtomatizirana kontrola ob prvem PR)
250- Sledenje [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/)
251- Glej [CONTRIBUTING.md](./CONTRIBUTING.md) za podrobna navodila
252- Navedi številke issue-ov v opisu PR, če je primerno
253 
254### Pregledni postopek
255 
256- PR-je pregledajo vzdrževalci in skupnost
257- Prioriteta je izobraževalna jasnost
258- Primeri kode sledijo najboljšim trenutnim praksam
259- Prevodi se pregledajo za natančnost in kulturno ustreznost
260 
261## Sistem prevajanja
262 
263### Avtomatizirani prevod
264 
265- Uporablja GitHub Actions z delovnim tokom co-op-translator
266- Samodejno prevaja v več kot 50 jezikov
267- Izvorne datoteke so v glavnih direktorijih
268- Prevedene datoteke v `translations/{jezikovna-koda}/`
269 
270### Dodajanje ročnih izboljšav prevodov
271 
2721. Najdi datoteko v `translations/{jezikovna-koda}/`
2732. Naredi izboljšave, ob ohranitvi strukture
2743. Poskrbi, da primeri kode ostanejo funkcionalni
2754. Testiraj lokalizirano vsebino kvizov
276 
277### Metapodatki prevodov
278 
279Prevedene datoteke vključujejo meta glavo:
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## Razhroščevanje in odpravljanje težav
293 
294### Pogoste težave
295 
296**Quiz app ne zažene**:
297- Preveri verzijo Node.js (priporočena v14+)
298- Izbriši `node_modules` in `package-lock.json`, ponovno zaženi `npm install`
299- Preveri morebitne konflikte vrat (privzeto: Vite uporablja port 5173)
300 
301**API strežnik se ne zažene**:
302- Preveri verzijo Node.js (node >=10)
303- Preveri, če je port že v uporabi
304- Poskrbi, da so vse odvisnosti nameščene z `npm install`
305 
306**Razširitev brskalnika se ne naloži**:
307- Preveri, da je manifest.json pravilno oblikovan
308- Preveri konzolo brskalnika za napake
309- Sledi navodilom za namestitev specifičnim za brskalnik
310 
311**Težave s projektom klepeta v Pythonu**:
312- Namesti paket OpenAI: `pip install openai`
313- Preveri, da je okoljska spremenljivka GITHUB_TOKEN nastavljena
314- Preveri dovoljenja za dostop do GitHub modelov
315 
316**Docsify ne postreže dokumentacije**:
317- Namesti docsify-cli globalno: `npm install -g docsify-cli`
318- Zaženi v korenski mapi skladišča
319- Preveri obstoj `docs/_sidebar.md`
320 
321### Nasveti za razvojno okolje
322 
323- Uporabljaj VS Code z razširitvijo Live Server za HTML projekte
324- Namesti razširitve ESLint in Prettier za skladno oblikovanje
325- Uporabljaj DevTools brskalnika za razhroščevanje JavaScript-a
326- Za Vue projekte namesti Vue DevTools brskalniško razširitev
327 
328### Upoštevanje zmogljivosti
329 
330- Veliko število prevedenih datotek (več kot 50 jezikov) pomeni velike polne klone
331- Uporabi plitki klon, če delaš le na vsebini: `git clone --depth 1`
332- Izključi prevode iz iskanj, ko delaš na angleški vsebini
333- Procesi gradnje so lahko počasnejši ob prvem zagonu (npm install, Vite build)
334 
335## Varnostni vidiki
336 
337### Okoljske spremenljivke
338 
339- Ključi API ne smejo biti nikoli vključeni v repozitorij
340- Uporabljaj `.env` datoteke (že vključene v `.gitignore`)
341- Dokumentiraj potrebne okoljske spremenljivke v README-jih projektov
342 
343### Python projekti
344 
345- Uporabljaj virtualna okolja: `python -m venv venv`
346- Posodabljaj odvisnosti
347- GitHub tokeni naj imajo minimalne potrebne pravice
348 
349### Dostop do GitHub modelov
350 
351- Za GitHub modele so potrebni osebni dostopni tokeni (PAT)
352- Tokeni morajo biti shranjeni kot okoljske spremenljivke
353- Tokenov ali poverilnic nikoli ne vključi v repozitorij
354 
355## Dodatne opombe
356 
357### Ciljna publika
358 
359- Popolni začetniki v spletni razvoj
360- Študenti in samouki
361- Učitelji, ki uporabljajo učni načrt v razredih
362- Vsebina je zasnovana za dostopnost in postopno gradnjo veščin
363 
364### Izobraževalna filozofija
365 
366- Pristop učenja na osnovi projektov
367- Pogoste preveritve znanja (kvizi)
368- Praktične vaje programiranja
369- Primeri uporabe iz realnega sveta
370- Osredotočenost na osnove pred ogrodji
371 
372### Vzdrževanje skladišča
373 
374- Aktivna skupnost učencev in prispevajočih
375- Redne posodobitve odvisnosti in vsebine
376- Vzdrževalci nadzorujejo težave in razprave
377- Prevodi se posodabljajo avtomatsko preko GitHub Actions
378 
379### Sorodni viri
380 
381- [Moduli Microsoft Learn](https://docs.microsoft.com/learn/)
382- [Viri Student Hub](https://docs.microsoft.com/learn/student-hub/)
383- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) priporočeno za učence
384- Dodatni tečaji: Generativna AI, Data Science, ML, IoT učni načrti na voljo
385 
386### Delo z določenimi projekti
387 
388Za podrobna navodila o posameznih projektih glej README datoteke v:
389- `quiz-app/README.md` - Vue 3 aplikacija kviza
390- `7-bank-project/README.md` - Bančna aplikacija z avtentikacijo
391- `5-browser-extension/README.md` - Razvoj razširitve brskalnika
392- `6-space-game/README.md` - Razvoj igre na platnu (Canvas)
393- `9-chat-project/README.md` - Projekt AI klepetalnega pomočnika
394 
395### Struktura monorepo
396 
397Čeprav ni tradicionalni monorepo, to skladišče vsebuje več samostojnih projektov:
398- Vsaka lekcija je samostojna
399- Projekti ne delijo odvisnosti
400- Delo na posameznih projektih brez vpliva na druge
401- Kloniraj celotno skladišče za celotno učni izkušnjo
402 
403---
404 
405<!-- CO-OP TRANSLATOR DISCLAIMER START -->
406**Omejitev odgovornosti**:  
407Ta dokument je bil preveden z uporabo storitve za prevajanje z umetno inteligenco [Co-op Translator](https://github.com/Azure/co-op-translator). Čeprav si prizadevamo za točnost, vas opozarjamo, da avtomatizirani prevodi lahko vsebujejo napake ali netočnosti. Izvirni dokument v njegovem izvirnem jeziku je treba obravnavati kot avtoritativni vir. Za ključne informacije priporočamo strokovni človeški prevod. Nismo odgovorni za morebitna nesporazume ali nepravilne interpretacije, ki izhajajo iz uporabe tega prevoda.
408<!-- CO-OP TRANSLATOR DISCLAIMER END -->