13 KiB

Raw Permalink Blame History

AGENTS.md

Prehľad projektu

Toto je vzdelávací repozitár pre výučbu základov webového vývoja pre začiatočníkov. Kurz je komplexný 12-týždňový program vyvinutý Microsoft Cloud Advocates, obsahujúci 24 praktických lekcií pokrývajúcich JavaScript, CSS a HTML.

Kľúčové komponenty

Vzdelávací obsah: 24 štruktúrovaných lekcií usporiadaných do modulov založených na projektoch
Praktické projekty: Terrárium, Hra na písanie, Rozšírenie prehliadača, Vesmírna hra, Banková aplikácia, Code Editor a AI Chat Asistent
Interaktívne kvízy: 48 kvízov s 3 otázkami v každom (pred/po lekcii)
Podpora viacerých jazykov: Automatizované preklady do 50+ jazykov cez GitHub Actions
Technológie: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (pre AI projekty)

Architektúra

Vzdelávací repozitár so štruktúrou založenou na lekciách
Každý priečinok lekcie obsahuje README, ukážky kódu a riešenia
Samostatné projekty v oddelených adresároch (quiz-app, rôzne projekty lekcií)
Prekladový systém využívajúci GitHub Actions (co-op-translator)
Dokumentácia podávaná cez Docsify a dostupná ako PDF

Príkazy na nastavenie

Tento repozitár je primárne na konzumáciu vzdelávacieho obsahu. Pre prácu s konkrétnymi projektmi:

Nastavenie hlavného repozitára

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

Nastavenie Quiz App (Vue 3 + Vite)

cd quiz-app
npm install
npm run dev        # Spustiť vývojový server
npm run build      # Vytvoriť pre produkciu
npm run lint       # Spustiť ESLint

API Bankového projektu (Node.js + Express)

cd 7-bank-project/api
npm install
npm start          # Spustiť API server
npm run lint       # Spustiť ESLint
npm run format     # Naformátovať pomocou Prettier

Projekty rozšírenia prehliadača

cd 5-browser-extension/solution
npm install
# Postupujte podľa pokynov na načítanie rozšírenia špecifických pre prehliadač

Projekty vesmírnej hry

cd 6-space-game/solution
npm install
# Otvorte index.html v prehliadači alebo použite Live Server

Projekt Chat (Python Backend)

cd 9-chat-project/solution/backend/python
pip install openai
# Nastavte premennú prostredia GITHUB_TOKEN
python api.py

Vývojový proces

Pre prispievateľov obsahu

Forknite repozitár do svojho GitHub účtu
Skloňujte svoj fork lokálne
Vytvorte novú vetvu pre svoje zmeny
Robte zmeny v obsahu lekcií alebo príkladoch kódu
Testujte akékoľvek zmeny kódu v relevantných projektových adresároch
Podajte pull request podľa pravidiel prispievania

Pre študentov

Forknite alebo naklonujte repozitár
Postupne prechádzajte adresáre lekcií
Čítajte README súbory pre každú lekciu
Vyplňte pre-lekčné kvízy na https://ff-quizzes.netlify.app/web/
Prejdite si príklady kódu v adresároch lekcií
Dokončite úlohy a výzvy
Absolvujte po-lekčné kvízy

Živý vývoj

Dokumentácia: Spustite docsify serve v koreňovom adresári (port 3000)
Quiz App: Spustite npm run dev v adresári quiz-app
Projekty: Použite VS Code Live Server rozšírenie pre HTML projekty
API projekty: Spustite npm start v príslušných API adresároch

Inštrukcie na testovanie

Testovanie Quiz App

cd quiz-app
npm run lint       # Skontrolujte problémy so štýlom kódu
npm run build      # Overte, či zostavenie prebehne úspešne

Testovanie Bank API

cd 7-bank-project/api
npm run lint       # Skontrolujte problémy so štýlom kódu
node server.js     # Overte, či server štartuje bez chýb

Všeobecný prístup k testovaniu

Ide o vzdelávací repozitár bez komplexných automatizovaných testov
Manuálne testovanie sa zameriava na:
- Príklady kódu bez chýb
- Funkčnosť odkazov v dokumentácii
- Úspešnosť buildov projektov
- Dodržiavanie najlepších praktík v príkladoch

Kontroly pred odoslaním

Spustite npm run lint v adresároch s package.json
Overte platnosť markdown odkazov
Testujte príklady kódu v prehliadači alebo Node.js
Skontrolujte, či preklady zachovávajú správnu štruktúru

Pravidlá štýlu kódu

JavaScript

Používajte moderný ES6+ syntax
Dodržiavajte štandardné ESLint konfigurácie v projektoch
Používajte zrozumiteľné názvy premenných a funkcií pre vzdelávaciu jasnosť
Pridávajte komentáre vysvetľujúce koncepty pre študentov
Formátujte kód pomocou Prettier kde je nastavený

HTML/CSS

Semantické HTML5 prvky
Principy responzívneho dizajnu
Čisté pomenovanie tried
Komentáre vysvetľujúce CSS techniky pre študentov

Python

Štýlové pravidlá PEP 8
Jasné, vzdelávacie príklady kódu
Typové anotácie tam, kde pomáhajú pri učení

Markdown dokumentácia

Jasná hierarchia nadpisov
Kódové bloky s určením jazyka
Odkazy na doplnkové zdroje
Snímky obrazovky a obrázky v adresároch images/
Alt text pre obrázky pre prístupnosť

Organizácia súborov

Lekcie číslované postupne (1-getting-started-lessons, 2-js-basics, atď.)
Každý projekt má adresáre solution/ a často start/ alebo your-work/
Obrázky uložené v špecifických priečinkoch lekcií images/
Preklady v štruktúre translations/{language-code}/

Build a nasadenie

Nasadenie Quiz App (Azure Static Web Apps)

quiz-app je nakonfigurovaný pre nasadenie na Azure Static Web Apps:

cd quiz-app
npm run build      # Vytvára priečinok dist/
# Nasadzuje cez GitHub Actions workflow pri push do main

Konfigurácia Azure Static Web Apps:

Umiestnenie aplikácie: /quiz-app
Výstupné miesto: dist
Workflow: .github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml

Generovanie PDF dokumentácie

npm install                    # Inštalujte docsify-to-pdf
npm run convert               # Vygenerujte PDF z docs

Dokumentácia cez Docsify

npm install -g docsify-cli    # Nainštalujte Docsify globálne
docsify serve                 # Spustite na localhost:3000

Buildy špecifické pre projekt

Každý projektový adresár môže mať svoj vlastný build proces:

Vue projekty: npm run build vytvára produkčné balíky
Statické projekty: žiadny build krok, súbory sa servujú priamo

Pravidlá pre pull requesty

Formát názvov

Používajte jasné a popisné názvy, ktoré indikujú oblasť zmeny:

[Quiz-app] Pridanie nového kvízu pre lekciu X
[Lesson-3] Oprava preklepu v projekte terrarium
[Translation] Pridanie španielskeho prekladu pre lekciu 5
[Docs] Aktualizácia inštrukcií na nastavenie

Povinné kontroly

Pred podaním PR:

Kvalita kódu:
- Spustite npm run lint v dotknutých projektových adresároch
- Opravte všetky linting chyby a varovania
Overenie build procesu:
- Spustite npm run build ak je to potrebné
- Zabezpečte, že neexistujú chyby pri buildovaní
Validácia odkazov:
- Otestujte všetky markdown odkazy
- Overte funkčnosť referencií obrázkov
Kontrola obsahu:
- Korektúra pravopisných a gramatických chýb
- Overte správnosť a vzdelávací charakter príkladov kódu
- Skontrolujte, či preklady zachovávajú pôvodný význam

Požiadavky na príspevky

Súhlas s Microsoft CLA (automatická kontrola pri prvom PR)
Dodržiavanie Microsoft Open Source Kódexu správania
Viac informácií v CONTRIBUTING.md
Pri PR uvádzať čísla issues, ak sú relevantné

Proces recenzie

PR sú kontrolované správcami a komunitou
Priorita na vzdelávaciu jasnosť
Príklady kódu musia dodržiavať aktuálne najlepšie praktiky
Preklady recenzované na presnosť a kultúrnu vhodnosť

Prekladový systém

Automatizovaný preklad

Používa GitHub Actions s workflow co-op-translator
Automaticky prekladá do 50+ jazykov
Zdrojové súbory v hlavných adresároch
Preložené súbory v adresároch translations/{language-code}/

Pridávanie manuálnych vylepšení prekladu

Nájdite súbor v translations/{language-code}/
Vylepšujte obsah so zachovaním štruktúry
Zaistite, aby príklady kódu boli funkčné
Otestujte lokalizovaný kvízový obsah

Metaúdaje prekladu

Preložené súbory obsahujú metaúdajový záhlavok:

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

Ladenie a riešenie problémov

Bežné problémy

Quiz app sa nespustí:

Skontrolujte verziu Node.js (odporúčané v14+)
Vymažte node_modules a package-lock.json, znova spustite npm install
Skontrolujte konflikty portov (predvolené: Vite používa port 5173)

API server sa nespustí:

Overte, že verzia Node.js je minimálne node >=10
Skontrolujte, či port nie je už obsadený
Uistite sa, že všetky závislosti sú nainštalované cez npm install

Rozšírenie prehliadača sa nenačíta:

Skontrolujte správne naformátovanie manifest.json
Prehliadačový konzolový výstup pre chyby
Postupujte podľa inštrukcií inštalácie podľa prehliadača

Problémy s Python chat projektom:

Skontrolujte inštaláciu balíčka OpenAI: pip install openai
Overte nastavenie premennej prostredia GITHUB_TOKEN
Skontrolujte oprávnenia prístupu k GitHub modelom

Docsify neservíruje dokumentáciu:

Nainštalujte docsify-cli globálne: npm install -g docsify-cli
Spusťte príkaz v koreňovom adresári repozitára
Skontrolujte, že existuje docs/_sidebar.md

Tipy pre vývojové prostredie

Používajte VS Code s Live Server rozšírením pre HTML projekty
Nainštalujte ESLint a Prettier rozšírenia pre konzistentné formátovanie
Použite DevTools v prehliadači na ladenie JavaScriptu
Pre Vue projekty nainštalujte Vue DevTools rozšírenie prehliadača

Výkonnostné aspekty

Veľký počet prekladových súborov (50+ jazykov) robí kompletné klony veľkými
Pre prácu len s obsahom použite plytký klon: git clone --depth 1
Vylúčte preklady z vyhľadávania pri práci s anglickým obsahom
Build procesy môžu byť pomalé pri prvom spustení (npm install, Vite build)

Bezpečnostné aspekty

Premenné prostredia

API kľúče nikdy neukladajte do repozitára
Používajte .env súbory (už zahrnuté v .gitignore)
Požadované premenné prostredia dokumentujte v README projektov

Python projekty

Používajte virtuálne prostredia: python -m venv venv
Udržiavajte závislosti aktuálne
GitHub tokeny majte s minimálnymi potrebnými právami

Prístup k GitHub Modelom

Vyžadujú sa osobné prístupové tokeny (PAT)
Tokeny ukladajte ako premenné prostredia
Nikdy neukladajte tokeny alebo prihlasovacie údaje do repozitára

Doplnkové poznámky

Cieľová skupina

Úplní začiatočníci vo webovom vývoji
Študenti a samoštudenti
Učitelia používajúci kurz v triedach
Obsah je navrhnutý pre prístupnosť a postupné zlepšovanie zručností

Vzdelávacia filozofia

Projektovo orientované učenie
Časté kontrolné testy (kvízy)
Praktické cvičenia v písaní kódu
Príklady z reálneho sveta
Zameranie na základy pred frameworkami

Údržba repozitára

Aktívna komunita študentov a prispievateľov
Pravidelné aktualizácie závislostí a obsahu
Sledovanie issues a diskusií správcami
Automatizované aktualizácie prekladov cez GitHub Actions

Súvisiace zdroje

Microsoft Learn moduly
Student Hub zdroje
GitHub Copilot odporúčaný pre študentov
Ďalšie kurzy: Generatívna AI, Data Science, ML, IoT dostupné

Práca s konkrétnymi projektmi

Podrobné inštrukcie k jednotlivým projektom nájdete v README súboroch:

quiz-app/README.md - Vue 3 quiz aplikácia
7-bank-project/README.md - Banková aplikácia s autentifikáciou
5-browser-extension/README.md - Vývoj rozšírenia prehliadača
6-space-game/README.md - Vývoj hry na canvas
9-chat-project/README.md - Projekt AI chat asistenta

Štruktúra monorepa

Aj keď nejde o tradičné monorepo, tento repozitár obsahuje viacero nezávislých projektov:

Každá lekcia je samostatná
Projekty nesdielajú závislosti
Pracujte na jednotlivých projektoch bez ovplyvnenia ostatných
Naklonujte celý repozitár pre kompletný kurzový zážitok

Zrieknutie sa zodpovednosti:
Tento dokument bol preložený pomocou služby AI prekladu Co-op Translator. Hoci sa snažíme o presnosť, majte, prosím, na pamäti, že automatizované preklady môžu obsahovať chyby alebo nepresnosti. Originálny dokument v jeho pôvodnom jazyku by mal byť považovaný za autoritatívny zdroj. Pre kritické informácie sa odporúča profesionálny ľudský preklad. Nie sme zodpovední za akékoľvek nepochopenia alebo nesprávne interpretácie vyplývajúce z použitia tohto prekladu.

13 KiB Raw Permalink Blame History