13 KiB

Raw Permalink Blame History

AGENTS.md

Pregled projekta

To je izobraževalni kurikulum repozitorij za poučevanje osnov spletnega razvoja začetnikom. Kurikulum je obsežen 12-tedenski tečaj, razvit s strani Microsoft Cloud Advocates, ki vsebuje 24 praktičnih lekcij, ki zajemajo JavaScript, CSS in HTML.

Ključne komponente

Izobraževalna vsebina: 24 strukturiranih lekcij, organiziranih v modulih, temelječih na projektih
Praktični projekti: Terrarium, igra tipkanja, razširitev brskalnika, igra v vesolju, bančna aplikacija, urejevalnik kode in AI klepetalni pomočnik
Interaktivni kvizi: 48 kvizov s po 3 vprašanji (pred/po lekciji)
Večjezična podpora: Samodejni prevodi za več kot 50 jezikov preko GitHub Actions
Tehnologije: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (za AI projekte)

Arhitektura

Izobraževalni repozitorij z organizacijo po lekcijah
Vsaka mapa lekcije vsebuje README, primeri kode in rešitve
Samostojni projekti v ločenih imenikih (quiz-app, različni projekti lekcij)
Sistem prevajanja z GitHub Actions (co-op-translator)
Dokumentacija strežena preko Docsify in dostopna kot PDF

Ukazi za nastavitev

Ta repozitorij je namenjen predvsem za porabo izobraževalne vsebine. Za delo s specifičnimi projekti:

Glavna nastavitev repozitorija

git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
cd Web-Dev-For-Beginners

Nastavitev Quiz Aplikacije (Vue 3 + Vite)

cd quiz-app
npm install
npm run dev        # Začni razvojni strežnik
npm run build      # Sestavi za proizvodnjo
npm run lint       # Zaženi ESLint

API bančnega projekta (Node.js + Express)

cd 7-bank-project/api
npm install
npm start          # Zaženi API strežnik
npm run lint       # Zaženi ESLint
npm run format     # Oblikuj s Prettierjem

Projekti razširitve brskalnika

cd 5-browser-extension/solution
npm install
# Sledite navodilom za nalaganje razširitve, specifičnim za brskalnik

Projekti igre v vesolju

cd 6-space-game/solution
npm install
# Odprite index.html v brskalniku ali uporabite Live Server

Klepetalni projekt (Python backend)

cd 9-chat-project/solution/backend/python
pip install openai
# Nastavite okoljsko spremenljivko GITHUB_TOKEN
python api.py

Razvojni potek dela

Za prispevne vsebine

Razveji repozitorij (fork) na svoj GitHub račun
Kloniraj svoj fork lokalno
Ustvari novo vejo za spremembe
Naredi spremembe vsebine lekcije ali primerov kode
Preizkusi spremembe kode v ustreznih mapah projektov
Pošlji pull request po navodilih za prispevke

Za učence

Razveji ali kloniraj repozitorij
Pomikaj se po lekcijah zaporedoma
Preberi README datoteke za vsako lekcijo
Reši pred-kvizove na https://ff-quizzes.netlify.app/web/
Delo z jeziki primeri v mapah lekcij
Opravi naloge in izzive
Reši post-kvizove

Živi razvoj

Dokumentacija: Zaženi docsify serve v korenski mapi (port 3000)
Quiz App: Zaženi npm run dev v mapi quiz-app
Projekti: Uporabi VS Code Live Server razširitev za HTML projekte
API Projekti: Zaženi npm start v ustreznih API mapah

Navodila za testiranje

Testiranje Quiz Aplikacije

cd quiz-app
npm run lint       # Preveri težave s slogom kode
npm run build      # Preveri, ali je sestavljanje uspešno

Testiranje Bank API

cd 7-bank-project/api
npm run lint       # Preverite težave s slogom kode
node server.js     # Preverite, ali se strežnik zažene brez napak

Splošni pristop testiranja

To je izobraževalni repozitorij brez obsežnih avtomatiziranih testov
Ročno testiranje se osredotoča na:
- Primeri kode tečejo brez napak
- Povezave v dokumentaciji delujejo pravilno
- Projekti se uspešno zgradijo
- Primeri sledijo najboljšim praksam

Preverjanje pred oddajo

Zaženi npm run lint v mapah z datoteko package.json
Preveri, da so povezave v markdownu veljavne
Testiraj primere kode v brskalniku ali Node.js
Preveri, da prevodi ohranjajo pravilno strukturo

Smernice za stil kode

JavaScript

Uporabi sodobno ES6+ sintakso
Upoštevaj standardne ESLint konfiguracije v projektih
Uporabi smiselna imena spremenljivk in funkcij za jasnost izobraževanja
Dodaj komentarje za razlago konceptov učencem
Formatiraj z orodjem Prettier, kjer je nastavljeno

HTML/CSS

Semantični HTML5 elementi
Načela odzivnega oblikovanja
Jasne konvencije imen razredov
Komentarji za razlago CSS tehnik učencem

Python

Smernice stila PEP 8
Jasni, izobraževalni primeri kode
Tipne namige, kjer pomagajo pri učenju

Dokumentacija v Markdownu

Jasna hierarhija naslovov
Bloki kode z določitvijo jezika
Povezave do dodatnih virov
Posnetki zaslona in slike v mapah images/
Alt besedilo za slike za dostopnost

Organizacija datotek

Lekcije zaporedno številčene (1-getting-started-lessons, 2-js-basics itd.)
Vsak projekt ima solution/ in pogosto tudi start/ ali your-work/ mape
Slike shranjene v lekcijsko specifičnih mapah images/
Prevodi v strukturi translations/{language-code}/

Gradnja in nameščanje

Namestitev Quiz Aplikacije (Azure Static Web Apps)

quiz-app je konfiguriran za nameščanje v Azure Static Web Apps:

cd quiz-app
npm run build      # Ustvari mapo dist/
# Izvedba z GitHub Actions potekom dela ob pushu na main

Konfiguracija Azure Static Web Apps:

Lokacija aplikacije: /quiz-app
Izhodna lokacija: dist
Potek dela: .github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml

Generiranje PDF dokumentacije

npm install                    # Namestite docsify-to-pdf
npm run convert               # Ustvari PDF iz docs

Dokumentacija Docsify

npm install -g docsify-cli    # Namestite Docsify globalno
docsify serve                 # Postrezi na localhost:3000

Gradnje za posamezne projekte

Vsaka projektna mapa ima lahko svoj postopek gradnje:

Vue projekti: npm run build ustvari produkcijske pakete
Statični projekti: Brez koraka gradnje, neposredno strežemo datoteke

Smernice za Pull Requeste

Oblika naslova

Uporabi jasne in opisne naslove, ki označujejo področje spremembe:

[Quiz-app] Dodaj nov kviz za lekcijo X
[Lesson-3] Popravi tipkarsko napako v projektu terrarium
[Translation] Dodaj španski prevod za lekcijo 5
[Docs] Posodobi navodila za nastavitev

Zahtevani pregledi

Pred oddajo PR:

Kakovost kode:
- Zaženi npm run lint v prizadetih projektnih mapah
- Odpravi vse napake in opozorila pri lintingu
Preverjanje gradnje:
- Zaženi npm run build, če je potrebno
- Poskrbi, da ni napak pri gradnji
Validacija povezav:
- Preizkusi vse markdown povezave
- Preveri delovanje referenc slik
Pregled vsebine:
- Preveri pravopis in slovnico
- Zagotovi, da so primeri kode pravilni in izobraževalni
- Preveri, da prevodi ohranjajo prvotni pomen

Zahteve za prispevke

Strinjanje z Microsoft CLA (avtomatizirana preveritev ob prvem PR)
Sledenje Microsoft Open Source Code of Conduct
Podrobna pravila so v CONTRIBUTING.md
V opisu PR navedi številke izdaj, če je relevantno

Postopek pregleda

PR pregledujejo vzdrževalci in skupnost
Prioriteta je jasnost izobraževalne vsebine
Primeri kode morajo slediti trenutnim najboljšim praksam
Prevodi se pregledajo za točnost in kulturno primernost

Sistem prevajanja

Samodejni prevod

Uporablja GitHub Actions z delovnim tokom co-op-translator
Samodejno prevaja v več kot 50 jezikov
Izvorne datoteke v glavnih mapah
Prevedene datoteke v translations/{language-code}/ mapah

Dodajanje ročnih izboljšav prevodov

Poišči datoteko v translations/{language-code}/
Naredi izboljšave ob ohranitvi strukture
Poskrbi, da primeri kode ostanejo funkcionalni
Testiraj vso lokalizirano vsebino kvizov

Metapodatki prevodov

Prevedene datoteke vsebujejo glavo z metapodatki:

<!--
CO_OP_TRANSLATOR_METADATA:
{
  "original_hash": "...",
  "translation_date": "...",
  "source_file": "...",
  "language_code": "..."
}
-->

Odpravljanje napak in reševanje težav

Pogoste težave

Quiz app se ne zažene:

Preveri verzijo Node.js (priporočeno v14+)
Izbriši node_modules in package-lock.json, ponovno zaženi npm install
Preveri konflikte portov (privzeto: Vite uporablja port 5173)

API strežnik se ne zažene:

Preveri, da je verzija Node.js zadostna (node >=10)
Preveri, če je port že v uporabi
Poskrbi, da so vse odvisnosti nameščene z npm install

Razširitev brskalnika se ne naloži:

Preveri, da je manifest.json pravilno oblikovan
Preveri napake v konzoli brskalnika
Sledi navodilom za nameščanje razširitev za določen brskalnik

Težave s Python klepetalnim projektom:

Poskrbi, da je paket OpenAI nameščen: pip install openai
Preveri, da je okoljska spremenljivka GITHUB_TOKEN nastavljena
Preveri dovoljenja za dostop do GitHub modelov

Docsify ne streže dokumentacije:

Namesti docsify-cli globalno: npm install -g docsify-cli
Zaženi iz korenske mape repozitorija
Preveri, da docs/_sidebar.md obstaja

Nasveti za razvojno okolje

Uporabi VS Code z Live Server razširitvijo za HTML projekte
Namesti ESLint in Prettier razširitve za dosledno oblikovanje
Uporabi brskalniška razvojna orodja za odpravljanje napak v JavaScriptu
Za Vue projekte namesti Vue DevTools brskalniško razširitev

Premisleki o zmogljivosti

Veliko število prevedenih datotek (više kot 50 jezikov) pomeni velike kloniranja
Uporabi plitev klon, če delaš le z vsebino: git clone --depth 1
Izključi prevode iz iskanj, ko delaš na angleški vsebini
Procesi gradnje so lahko počasni ob prvem izvajanju (npm install, Vite build)

Varnostni premisleki

Okoljske spremenljivke

API ključi nikoli ne smejo biti v repozitoriju
Uporabi .env datoteke (že vključene v .gitignore)
Dokumentiraj zahtevane okoljske spremenljivke v README projektov

Python projekti

Uporabi virtualna okolja: python -m venv venv
Ohrani odvisnosti posodobljene
GitHub tokeni naj imajo minimalne potrebne pravice

Dostop do GitHub modelov

Potrebni so osebni dostopni tokeni (PAT) za GitHub modele
Tokeni naj bodo shranjeni kot okoljske spremenljivke
Nikoli ne komitiraj tokenov ali poverilnic

Dodatne opombe

Ciljna publika

Popolni začetniki v spletnem razvoju
Študenti in samouki
Učitelji, ki uporabljajo kurikulum v učilnicah
Vsebina je zasnovana za dostopnost in postopno gradnjo veščin

Izobraževalna filozofija

Pristop učenja preko projektov
Pogoste preveritve znanja (kvizi)
Praktične vaje s kodiranjem
Primeri uporabe v resničnem svetu
Osredotočenost na osnove pred ogrodji

Vzdrževanje repozitorija

Aktivna skupnost učencev in prispevnikov
Redne posodobitve odvisnosti in vsebine
Izzivi in razprave nadzirani s strani vzdrževalcev
Posodobitve prevodov avtomatizirane preko GitHub Actions

Sorodni viri

Microsoft Learn moduli
Student Hub viri
Priporočeno za učence: GitHub Copilot
Dodatni tečaji: Generativna AI, podatkovna znanost, ML, IoT kurikuli

Delo s specifičnimi projekti

Za podrobna navodila glede posameznih projektov glej README datoteke v:

quiz-app/README.md - Vue 3 kviz aplikacija
7-bank-project/README.md - Bančna aplikacija z avtentikacijo
5-browser-extension/README.md - Razvoj razširitve brskalnika
6-space-game/README.md - Razvoj igre na platnu (canvas)
9-chat-project/README.md - AI klepetalni pomočnik

Struktura monorepa

Čeprav ni klasični monorepo, ta repozitorij vsebuje več neodvisnih projektov:

Vsaka lekcija je samostojna
Projekti ne delijo odvisnosti
Delo na posameznih projektih brez vpliva na ostale
Kloniraj celoten repozitorij za celotno kurikulum izkušnjo

Omejitev odgovornosti:
Ta dokument je bil preveden z uporabo storitve za AI prevajanje Co-op Translator. Čeprav si prizadevamo za natančnost, prosimo, upoštevajte, da avtomatizirani prevodi lahko vsebujejo napake ali netočnosti. Izvirni dokument v njegovem izvirnem jeziku je treba šteti za avtoritativni vir. Za ključne informacije je priporočljivo uporabiti strokovni človeški prevod. Nismo odgovorni za morebitna nesporazume ali napačne interpretacije, ki izhajajo iz uporabe tega prevoda.

13 KiB Raw Permalink Blame History