13 KiB

Raw Permalink Blame History

AGENTS.md

Pregled projekta

To 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.

Ključne sestavine

Izobraževalna vsebina: 24 strukturiranih lekcij, organiziranih v modulih na osnovi projektov
Praktični projekti: Terarij, Tipkovniška igra, Razširitev brskalnika, Vesoljska igra, Bančna aplikacija, Urejevalnik kode in AI klepetalni pomočnik
Interaktivni kvizi: 48 kvizov s 3 vprašanji vsak (pred in po lekciji)
Podpora za več jezikov: Avtomatizirani 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

Učni skladišče z strukturo na osnovi lekcij
Vsaka mapa lekcije vsebuje README, primere kode in rešitve
Samostojni projekti v ločenih imenikih (quiz-app, različni lekcijski projekti)
Sistem za prevajanje z uporabo GitHub Actions (co-op-translator)
Dokumentacija, postrežena preko Docsify in dostopna kot PDF

Ukazi za nastavitev

To skladišče je primarno namenjeno za uživanje izobraževalne vsebine. Za delo z določenimi projekti:

Nastavitev glavnega skladišča

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

Nastavitev Quiz App (Vue 3 + Vite)

cd quiz-app
npm install
npm run dev        # Zaženi razvojni strežnik
npm run build      # Zgradi za produkcijo
npm run lint       # Zaženi ESLint

API projekta Banka (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širitev brskalnika

cd 5-browser-extension/solution
npm install
# Upoštevajte navodila za nalaganje razširitev, specifična za brskalnik

Projekti vesoljske igre

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

Projekt klepeta (Python Backend)

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

Razvojni potek dela

Za prispevatele vsebine

Razvezi skladišče (fork) v svoj GitHub račun
Kloniraj svoj fork lokalno
Ustvari nov podal (branch) za svoje spremembe
Naredi spremembe v vsebini lekcij ali primerih kode
Testiraj spremembe kode v ustreznih mapah projektov
Pošlji pull requeste v skladu z navodili za prispevanje

Za učence

Razvezi ali kloniraj skladišče
Pomakni se zaporedno skozi mape lekcij
Preberi README datoteke za vsako lekcijo
Reši predlečnične kvize na https://ff-quizzes.netlify.app/web/
Delaj skozi primere kode v mapah lekcij
Dokončaj naloge in izzive
Reši postlečnične kvize

Živ razvoj

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

Navodila za testiranje

Testiranje Quiz App

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

Testiranje Bank API

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

Splošni pristop k testiranju

To je učni repozitorij brez celovitega avtomatskega testiranja
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 veljavnost povezav v markdownu
Testiraj primere kode v brskalniku ali Node.js
Preveri, da prevodi ohranjajo pravilno strukturo

Smernice za stil kode

JavaScript

Uporaba sodobne sintakse ES6+
Sledenje standardnim ESLint konfiguracijam, podanim v projektih
Uporaba pomenljivih imen spremenljivk in funkcij za lažje razumevanje
Dodajanje komentarjev za pojasnitev konceptov za učence
Formatiranje z uporabo Prettier kjer je konfigurirano

HTML/CSS

Semantični elementi HTML5
Principi odzivnega oblikovanja
Jasne konvencije poimenovanja razredov
Komentarji, ki pojasnjujejo CSS tehnike za učence

Python

Slediti smernicam sloga PEP 8
Jasni, izobraževalni primeri kode
Tipiziranje (type hints) kjer je koristno za učenje

Dokumentacija v Markdownu

Jasna hierarhija naslovov
Bloki kode z navedbo jezika
Povezave do dodatnih virov
Posnetki zaslona in slike v mapah images/
Alt besedilo za slike zaradi dostopnosti

Organizacija datotek

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

Sestavljanje in nameščanje

Namestitev Quiz App (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/
# Izvede namestitev prek GitHub Actions poteka ob potisku na main

Konfiguracija Azure Static Web Apps:

Lokacija aplikacije: /quiz-app
Izhodna lokacija: dist
Delovni tok: .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                 # Strežnik na localhost:3000

Gradnje specifične za projekte

Vsaka mapa projekta lahko ima lasten postopek gradnje:

Vue projekti: npm run build ustvari produkcijske pakete
Statični projekti: brez koraka gradnje, postreže se datoteke neposredno

Smernice za pull requeste

Oblika naslova

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

[Quiz-app] Dodaj nov kviz za lekcijo X
[Lesson-3] Popravi tipkarsko napako v projektu terarij
[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 linterja
Preverjanje gradnje:
- Zaženi npm run build če je potrebno
- Prepričaj se, da ni napak pri gradnji
Preverjanje povezav:
- Testiraj vse markdown povezave
- Preveri delovanje referenc slik
Pregled vsebine:
- Preveri pravopis in slovnico
- Zagotovi, da so primeri kode pravilni in poučni
- Preveri, da prevodi ohranjajo originalni pomen

Zahteve za prispevanje

Strinjanje z Microsoft CLA (avtomatizirana kontrola ob prvem PR)
Sledenje Microsoft Open Source Code of Conduct
Glej CONTRIBUTING.md za podrobna navodila
Navedi številke issue-ov v opisu PR, če je primerno

Pregledni postopek

PR-je pregledajo vzdrževalci in skupnost
Prioriteta je izobraževalna jasnost
Primeri kode sledijo najboljšim trenutnim praksam
Prevodi se pregledajo za natančnost in kulturno ustreznost

Sistem prevajanja

Avtomatizirani prevod

Uporablja GitHub Actions z delovnim tokom co-op-translator
Samodejno prevaja v več kot 50 jezikov
Izvorne datoteke so v glavnih direktorijih
Prevedene datoteke v translations/{jezikovna-koda}/

Dodajanje ročnih izboljšav prevodov

Najdi datoteko v translations/{jezikovna-koda}/
Naredi izboljšave, ob ohranitvi strukture
Poskrbi, da primeri kode ostanejo funkcionalni
Testiraj lokalizirano vsebino kvizov

Metapodatki prevodov

Prevedene datoteke vključujejo meta glavo:

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

Razhroščevanje in odpravljanje težav

Pogoste težave

Quiz app ne zažene:

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

API strežnik se ne zažene:

Preveri verzijo Node.js (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 konzolo brskalnika za napake
Sledi navodilom za namestitev specifičnim za brskalnik

Težave s projektom klepeta v Pythonu:

Namesti paket OpenAI: pip install openai
Preveri, da je okoljska spremenljivka GITHUB_TOKEN nastavljena
Preveri dovoljenja za dostop do GitHub modelov

Docsify ne postreže dokumentacije:

Namesti docsify-cli globalno: npm install -g docsify-cli
Zaženi v korenski mapi skladišča
Preveri obstoj docs/_sidebar.md

Nasveti za razvojno okolje

Uporabljaj VS Code z razširitvijo Live Server za HTML projekte
Namesti razširitve ESLint in Prettier za skladno oblikovanje
Uporabljaj DevTools brskalnika za razhroščevanje JavaScript-a
Za Vue projekte namesti Vue DevTools brskalniško razširitev

Upoštevanje zmogljivosti

Veliko število prevedenih datotek (več kot 50 jezikov) pomeni velike polne klone
Uporabi plitki klon, če delaš le na vsebini: git clone --depth 1
Izključi prevode iz iskanj, ko delaš na angleški vsebini
Procesi gradnje so lahko počasnejši ob prvem zagonu (npm install, Vite build)

Varnostni vidiki

Okoljske spremenljivke

Ključi API ne smejo biti nikoli vključeni v repozitorij
Uporabljaj .env datoteke (že vključene v .gitignore)
Dokumentiraj potrebne okoljske spremenljivke v README-jih projektov

Python projekti

Uporabljaj virtualna okolja: python -m venv venv
Posodabljaj odvisnosti
GitHub tokeni naj imajo minimalne potrebne pravice

Dostop do GitHub modelov

Za GitHub modele so potrebni osebni dostopni tokeni (PAT)
Tokeni morajo biti shranjeni kot okoljske spremenljivke
Tokenov ali poverilnic nikoli ne vključi v repozitorij

Dodatne opombe

Ciljna publika

Popolni začetniki v spletni razvoj
Študenti in samouki
Učitelji, ki uporabljajo učni načrt v razredih
Vsebina je zasnovana za dostopnost in postopno gradnjo veščin

Izobraževalna filozofija

Pristop učenja na osnovi projektov
Pogoste preveritve znanja (kvizi)
Praktične vaje programiranja
Primeri uporabe iz realnega sveta
Osredotočenost na osnove pred ogrodji

Vzdrževanje skladišča

Aktivna skupnost učencev in prispevajočih
Redne posodobitve odvisnosti in vsebine
Vzdrževalci nadzorujejo težave in razprave
Prevodi se posodabljajo avtomatsko preko GitHub Actions

Sorodni viri

Moduli Microsoft Learn
Viri Student Hub
GitHub Copilot priporočeno za učence
Dodatni tečaji: Generativna AI, Data Science, ML, IoT učni načrti na voljo

Delo z določenimi projekti

Za podrobna navodila o posameznih projektih glej README datoteke v:

quiz-app/README.md - Vue 3 aplikacija kviza
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 - Projekt AI klepetalnega pomočnika

Struktura monorepo

Čeprav ni tradicionalni monorepo, to skladišče vsebuje več samostojnih projektov:

Vsaka lekcija je samostojna
Projekti ne delijo odvisnosti
Delo na posameznih projektih brez vpliva na druge
Kloniraj celotno skladišče za celotno učni izkušnjo

Omejitev odgovornosti:
Ta dokument je bil preveden z uporabo storitve za prevajanje z umetno inteligenco 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.

13 KiB Raw Permalink Blame History