AGENTS.md

1# AGENTS.md
2 
3## Projekto apžvalga
4 
5Tai yra švietimo programa skirta mokyti pradedančiuosius interneto kūrimo pagrindų. Programa yra išsami 12 savaičių kursų sistema, sukurta Microsoft Cloud Advocates komandos, apimanti 24 praktines pamokas apie JavaScript, CSS ir HTML.
6 
7### Pagrindinės sudedamosios dalys
8 
9- **Švietimo turinys**: 24 struktūruotos pamokos, suskirstytos į projektų modulius
10- **Praktiniai projektai**: Terariumas, Rašymo žaidimas, Naršyklės plėtinys, Kosminis žaidimas, Banko programa, Kodo redaktorius ir AI pokalbių asistentas
11- **Interaktyvūs testai**: 48 testai po 3 klausimus kiekviename (prieš ir po pamokų įvertinimai)
12- **Daugiakalbė palaikymas**: Automatizuoti vertimai į 50+ kalbų naudojant GitHub Actions
13- **Technologijos**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (AI projektams)
14 
15### Architektūra
16 
17- Švietimo saugykla su pamokomis pagrįsta struktūra
18- Kiekvienos pamokos aplanke yra README, kodo pavyzdžiai ir sprendimai
19- Atskiri projektai atskiruose kataloguose (quiz-app, įvairūs pamokų projektai)
20- Vertimo sistema naudojant GitHub Actions (co-op-translator)
21- Dokumentacija pateikiama per Docsify ir prieinama PDF formatu
22 
23## Diegimo komandos
24 
25Šis saugykla yra skirta pirminiam švietimo turinio vartojimui. Dirbant su konkrečiais projektais:
26 
27### Pagrindinės saugyklos paruošimas
28 
29```bash
30git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
31cd Web-Dev-For-Beginners
32```
33 
34### Testų programėlės paruošimas (Vue 3 + Vite)
35 
36```bash
37cd quiz-app
38npm install
39npm run dev        # Paleisti kūrimo serverį
40npm run build      # Sukurti gamybai
41npm run lint       # Vykdyti ESLint
42```
43 
44### Banko projekto API (Node.js + Express)
45 
46```bash
47cd 7-bank-project/api
48npm install
49npm start          # Paleisti API serverį
50npm run lint       # Vykdyti ESLint
51npm run format     # Formatuoti su Prettier
52```
53 
54### Naršyklės plėtinių projektai
55 
56```bash
57cd 5-browser-extension/solution
58npm install
59# Vadovaukitės naršyklei būdingomis plėtinių įkėlimo instrukcijomis
60```
61 
62### Kosminio žaidimo projektai
63 
64```bash
65cd 6-space-game/solution
66npm install
67# Atidarykite index.html naršyklėje arba naudokite Live Server
68```
69 
70### Pokalbių projektas (Python serveris)
71 
72```bash
73cd 9-chat-project/solution/backend/python
74pip install openai
75# Nustatyti GITHUB_TOKEN aplinkos kintamąjį
76python api.py
77```
78 
79## Vystymo darbo eiga
80 
81### Turinį prisidedantiems
82 
831. **Atšakokite saugyklą** į savo GitHub paskyrą
842. **Klonuokite savo atšaką** lokaliai
853. **Sukurkite naują šaką** savo pakeitimams
864. Atlikite turinio ar kodo pavyzdžių pakeitimus pamokose
875. Patikrinkite kodo pakeitimus atitinkamuose projekto kataloguose
886. Pateikite pull requests laikantis indėlio taisyklių
89 
90### Mokiniams
91 
921. Atšakokite arba klonuokite saugyklą
932. Eikite sekantiems pamokų katalogams paeiliui
943. Skaitykite kiekvienos pamokos README failus
954. Atlikite priešpamokinius testus https://ff-quizzes.netlify.app/web/
965. Dirbkite su kodo pavyzdžiais pamokų aplankuose
976. Atlikite užduotis ir iššūkius
987. Atlikite pastraipinius testus
99 
100### Tiesioginis vystymas
101 
102- **Dokumentacija**: paleiskite `docsify serve` pagrindiniame kataloge (portas 3000)
103- **Testų programėlė**: paleiskite `npm run dev` quiz-app kataloge
104- **Projektai**: naudokite VS Code Live Server plėtinį HTML projektams
105- **API projektai**: paleiskite `npm start` atitinkamuose API kataloguose
106 
107## Testavimo instrukcijos
108 
109### Testų programėlės testavimas
110 
111```bash
112cd quiz-app
113npm run lint       # Patikrinkite kodo stiliaus problemas
114npm run build      # Patikrinkite, ar statyba sėkminga
115```
116 
117### Banko API testavimas
118 
119```bash
120cd 7-bank-project/api
121npm run lint       # Patikrinti kodo stiliaus problemas
122node server.js     # Patvirtinti, kad serveris paleidžiamas be klaidų
123```
124 
125### Bendras testavimo metodas
126 
127- Tai švietimo saugykla be išsamios automatizuotos testavimo sistemos
128- Rankinis testavimas orientuotas į:
129  - Kodo pavyzdžių vykdymą be klaidų
130  - Dokumentacijos nuorodų veikimą
131  - Projekto sėkmingą sudarymą
132  - Pavyzdžius atitinkančius gerąsias praktikas
133 
134### Prieš pateikiant patikrinimus
135 
136- Paleiskite `npm run lint` kataloguose su package.json
137- Patikrinkite markdown nuorodų galiojimą
138- Testuokite kodo pavyzdžius naršyklėje arba Node.js aplinkoje
139- Įsitikinkite, kad vertimai išlaiko tinkamą struktūrą
140 
141## Kodo stiliaus gairės
142 
143### JavaScript
144 
145- Naudoti modernią ES6+ sintaksę
146- Laikytis standartinių ESLint konfigūracijų projektuose
147- Naudoti prasmingus kintamųjų ir funkcijų pavadinimus švietimui aiškinti
148- Pridėti komentarus konceptų paaiškinimui mokiniams
149- Formatuoti su Prettier, jei konfigūruota
150 
151### HTML/CSS
152 
153- Semantikos atitinkantys HTML5 elementai
154- Reaguojantis dizainas
155- Aiškios klasių pavadinimų konvencijos
156- Komentarai CSS technikoms paaiškinti mokiniams
157 
158### Python
159 
160- PEP 8 stiliaus gairės
161- Aiškūs, švietimui skirti kodo pavyzdžiai
162- Tipo užuominos, jei padeda mokymuisi
163 
164### Markdown dokumentacija
165 
166- Aiški antraščių hierarchija
167- Kodo blokai su kalbos nurodymu
168- Nuorodos į papildomus išteklius
169- Ekrano kopijos ir paveikslėliai `images/` kataloguose
170- Alternatyvus tekstas paveikslėliams, siekiant prieinamumo
171 
172### Failų organizavimas
173 
174- Pamokos su numeriais paeiliui (1-getting-started-lessons, 2-js-basics ir kt.)
175- Kiekvienas projektas turi `solution/` ir dažnai `start/` arba `your-work/` katalogus
176- Paveikslėliai saugomi pamokai priskirtuose `images/` aplankuose
177- Vertimai saugomi `translations/{language-code}/` kataloguose
178 
179## Sudarymas ir diegimas
180 
181### Testų programėlės diegimas (Azure Static Web Apps)
182 
183quiz-app yra sukonfigūruota Azure Static Web Apps diegimui:
184 
185```bash
186cd quiz-app
187npm run build      # Sukuria dist/ aplanką
188# Diegia naudojant GitHub Actions darbo eigą, kai stumiama į main
189```
190 
191Azure Static Web Apps konfiguracija:
192- **Programėlės vieta**: `/quiz-app`
193- **Išvesties vieta**: `dist`
194- **Darbo eiga**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`
195 
196### Dokumentacijos PDF generavimas
197 
198```bash
199npm install                    # Įdiekite docsify-to-pdf
200npm run convert               # Sugeneruoti PDF iš dokumentų
201```
202 
203### Docsify dokumentacija
204 
205```bash
206npm install -g docsify-cli    # Įdiekite Docsify globaliai
207docsify serve                 # Paleiskite serveryje localhost:3000
208```
209 
210### Projektui specifiniai sudarymai
211 
212Kiekvienas projekto katalogas gali turėti savo sudarymo procesą:
213- Vue projektai: `npm run build` sukuria gamybines pakuotes
214- Statiniai projektai: nėra sudarymo žingsnio, failai pateikiami tiesiogiai
215 
216## Pull Request gairės
217 
218### Antraštės formatas
219 
220Naudokite aiškius, aprašomuosius pavadinimus, nurodančius pakeitimo sritį:
221- `[Quiz-app] Pridėti naują testą pamokai X`
222- `[Lesson-3] Ištaisyti klaidą terariumo projekte`
223- `[Translation] Pridėti ispanų vertimą pamokai 5`
224- `[Docs] Atnaujinti diegimo instrukcijas`
225 
226### Būtini patikrinimai
227 
228Prieš pateikiant PR:
229 
2301. **Kodo kokybė**:
231   - Paleiskite `npm run lint` paveiktuose projekto kataloguose
232   - Ištaisykite visas lint klaidas ir įspėjimus
233 
2342. **Sudarymo patikra**:
235   - Jei taikoma, paleiskite `npm run build`
236   - Užtikrinkite, kad nėra sudarymo klaidų
237 
2383. **Nuorodų validacija**:
239   - Išbandykite visas markdown nuorodas
240   - Patikrinkite, ar paveikslėlių nuorodos veikia
241 
2424. **Turinio peržiūra**:
243   - Tikrinkite rašybą ir gramatiką
244   - Užtikrinkite, kad kodo pavyzdžiai tinkami ir švietimo tikslais
245   - Patikrinkite, ar vertimai išlaiko pradinę prasmę
246 
247### Indėlio reikalavimai
248 
249- Sutikite su Microsoft CLA (automatinis tikrinimas pirmo PR metu)
250- Vadovaukitės [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/)
251- Peržiūrėkite [CONTRIBUTING.md](./CONTRIBUTING.md) dėl išsamios informacijos
252- Nurodykite klausimų numerius PR aprašyme, jei taikoma
253 
254### Apžvalgos procesas
255 
256- PR apžvelgia priežiūrėtojai ir bendruomenė
257- Prioritetas teikiamas mokymosi aiškumui
258- Kodo pavyzdžiai turi laikytis dabartinių geriausių praktikų
259- Vertimai peržiūrimi dėl tikslumo ir kultūrinio atitikimo
260 
261## Vertimo sistema
262 
263### Automatizuotas vertimas
264 
265- Naudoja GitHub Actions su co-op-translator darbo eiga
266- Automatiškai verčia į 50+ kalbų
267- Šaltinio failai pagrindiniuose kataloguose
268- Išversti failai saugomi `translations/{language-code}/` kataloguose
269 
270### Rankinių vertimo patobulinimų pridedimas
271 
2721. Suraskite failą `translations/{language-code}/`
2732. Atlikite patobulinimus išlaikant struktūrą
2743. Įsitikinkite, kad kodo pavyzdžiai veikia teisingai
2754. Išbandykite lokalizuotą testų turinį
276 
277### Vertimų metaduomenys
278 
279Išversti failai turi metaduomenų antraštę:
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## Derinimas ir problemų sprendimas
293 
294### Dažniausios problemos
295 
296**Testų programėlė nesikrauna**:
297- Patikrinkite Node.js versiją (rekomenduojama v14+)
298- Ištrinkite `node_modules` ir `package-lock.json`, paleiskite dar kartą `npm install`
299- Patikrinkite ar nėra uosto konflikto (numatytas: Vite naudoja 5173 portą)
300 
301**API serveris nesikrauna**:
302- Įsitikinkite, kad Node.js versija atitinka minimalią (node >=10)
303- Patikrinkite, ar uostas jau nenaudojamas
304- Įsitikinkite, kad visos priklausomybės įdiegtos su `npm install`
305 
306**Naršyklės plėtinys nesikrauna**:
307- Patikrinkite, ar manifest.json teisingai suformatuotas
308- Peržiūrėkite naršyklės konsolę dėl klaidų
309- Sekite naršyklės specifines plėtinių diegimo instrukcijas
310 
311**Python pokalbių projekto problemos**:
312- Įdiekite OpenAI paketą: `pip install openai`
313- Įsitikinkite, kad GITHUB_TOKEN aplinkos kintamasis nustatytas
314- Patikrinkite GitHub Models prieigos teises
315 
316**Docsify neduoda dokumentų**:
317- Įdiekite docsify-cli globaliai: `npm install -g docsify-cli`
318- Paleiskite iš saugyklos šaknies
319- Patikrinkite, ar egzistuoja `docs/_sidebar.md`
320 
321### Vystymo aplinkos patarimai
322 
323- Naudokite VS Code su Live Server plėtiniu HTML projektams
324- Įdiekite ESLint ir Prettier plėtinius nuosekliam formatavimui
325- Naudokite naršyklės DevTools JavaScript derinimui
326- Vue projektams naudokite Vue DevTools naršyklės plėtinį
327 
328### Veikimo efektyvumo patarimai
329 
330- Didelis išverstų failų kiekis (50+ kalbų) reiškia, kad pilni klonai dideli
331- Naudokite paviršinį klonavimą, jei dirbate tik su turiniu: `git clone --depth 1`
332- Dirbant su anglišku turiniu, išimkite vertimus iš paieškos
333- Sudarymo procesai pirmą kartą gali būti lėti (npm install, Vite build)
334 
335## Saugumo aspektai
336 
337### Aplinkos kintamieji
338 
339- API raktai niekada neturi būti įtraukiami į saugyklą
340- Naudokite `.env` failus (jau įtraukti į `.gitignore`)
341- Reikalingi aplinkos kintamieji dokumentuojami projekto README
342 
343### Python projektai
344 
345- Naudokite virtualias aplinkas: `python -m venv venv`
346- Laikykite priklausomybes atnaujintas
347- GitHub tokenai turėtų turėti minimalias būtinas teises
348 
349### GitHub Models prieiga
350 
351- Reikalingi asmeniniai prieigos raktai (PAT)
352- Raktai turi būti saugomi kaip aplinkos kintamieji
353- Niekada neįtraukti jų į saugyklą ar viešinti
354 
355## Papildomos pastabos
356 
357### Tikslinė auditorija
358 
359- Visiškai pradedantieji interneto kūrime
360- Studentai ir savarankiški besimokantieji
361- Mokytojai, naudojantys programą klasėje
362- Turinys sukonstruotas prieinamumui ir nuosekliam įgūdžių įgijimui
363 
364### Švietimo filosofija
365 
366- Mokymasis pagrįstas projektais
367- Dažni žinių patikrinimai (testai)
368- Praktiniai kodavimo užsiėmimai
369- Realių projektų pavyzdžiai
370- Dėmesys pagrindams prieš frameworks
371 
372### Saugyklos priežiūra
373 
374- Aktyvi mokinių ir prisidėjusių bendruomenė
375- Reguliarūs priklausomybių ir turinio atnaujinimai
376- Klausimai ir diskusijos prižiūrimi saugyklos savininkų
377- Vertimų atnaujinimai automatizuoti per GitHub Actions
378 
379### Susiję ištekliai
380 
381- [Microsoft Learn moduliai](https://docs.microsoft.com/learn/)
382- [Studentų centras](https://docs.microsoft.com/learn/student-hub/)
383- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) rekomenduojamas besimokantiesiems
384- Papildomi kursai: Generatyvioji AI, Duomenų mokslas, ML, IoT programos
385 
386### Darbas su konkrečiais projektais
387 
388Išsamios individualių projektų instrukcijos pateiktos README failuose:
389- `quiz-app/README.md` - Vue 3 testų programėlė
390- `7-bank-project/README.md` - Banko programa su autentifikacija
391- `5-browser-extension/README.md` - Naršyklės plėtinių kūrimas
392- `6-space-game/README.md` - Žaidimas su Canvas
393- `9-chat-project/README.md` - AI pokalbių asistento projektas
394 
395### Monorepo struktūra
396 
397Nors tai nėra tradicinis monorepo, ši saugykla turi kelis nepriklausomus projektus:
398- Kiekviena pamoka yra savarankiška
399- Projektai nesidalina priklausomybėmis
400- Darbai su atskirais projektais neturi įtakos kitiems
401- Klonuokite visą saugyklą pilnam kursui gauti
402 
403---
404 
405<!-- CO-OP TRANSLATOR DISCLAIMER START -->
406**Atsakomybės ribojimas**:
407Šis dokumentas buvo išverstas naudojant dirbtinio intelekto vertimo paslaugą [Co-op Translator](https://github.com/Azure/co-op-translator). Nors stengiamės užtikrinti tikslumą, atkreipkite dėmesį, kad automatizuoti vertimai gali turėti klaidų ar netikslumų. Originalus dokumentas jo gimtąja kalba yra laikomas autoritetingu šaltiniu. Svarbiai informacijai rekomenduojamas profesionalus žmogiškasis vertimas. Mes neatsakome už bet kokius nesusipratimus ar klaidingas interpretacijas, kylančias naudojant šį vertimą.
408<!-- CO-OP TRANSLATOR DISCLAIMER END -->