13 KiB

Raw Permalink Blame History

AGENTS.md

Pregled projekta

Ovo je repozitorij s obrazovnim planom i programom za podučavanje osnova web razvoja početnicima. Plan i program je sveobuhvatan tečaj u trajanju od 12 tjedana koji su razvili Microsoft Cloud Advocates, sadrži 24 praktične lekcije koje pokrivaju JavaScript, CSS i HTML.

Ključne komponente

Obrazovni sadržaj: 24 strukturirane lekcije organizirane u module temeljene na projektima
Praktični projekti: Terrarij, Igra tipkanja, Proširenje preglednika, Svemirska igra, Bankovna aplikacija, Uređivač koda i AI pomoćnik za chat
Interaktivni kvizovi: 48 kvizova s po 3 pitanja (procjena prije i nakon lekcije)
Višejezična podrška: Automatski prijevodi na više od 50 jezika putem GitHub Actions
Tehnologije: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (za AI projekte)

Arhitektura

Obrazovni repozitorij s lekcijski organiziranom strukturom
Svaka mapa lekcije sadrži README, primjere koda i rješenja
Samostalni projekti u zasebnim direktorijima (quiz-app, razni projektni lekcijski folderi)
Sustav prijevoda preko GitHub Actions (co-op-translator)
Dokumentacija poslužena putem Docsify i dostupna kao PDF

Komande za postavljanje

Ovaj repozitorij prvenstveno služi za konzumaciju obrazovnog sadržaja. Za rad s određenim projektima:

Postavljanje glavnog repozitorija

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

Postavljanje Quiz Aplikacije (Vue 3 + Vite)

cd quiz-app
npm install
npm run dev        # Pokreni razvojni poslužitelj
npm run build      # Izgradi za produkciju
npm run lint       # Pokreni ESLint

API projekta banke (Node.js + Express)

cd 7-bank-project/api
npm install
npm start          # Pokreni API server
npm run lint       # Pokreni ESLint
npm run format     # Formatiraj s Prettier

Projekti proširenja preglednika

cd 5-browser-extension/solution
npm install
# Slijedite upute za učitavanje proširenja specifične za preglednik

Projekti svemirske igre

cd 6-space-game/solution
npm install
# Otvorite index.html u pregledniku ili koristite Live Server

Projekt chata (Python Backend)

cd 9-chat-project/solution/backend/python
pip install openai
# Postavite varijablu okoline GITHUB_TOKEN
python api.py

Radni tok razvoja

Za suradnike na sadržaju

Forkajte repozitorij na svoj GitHub račun
Klonirajte svoj fork lokalno
Kreirajte novu granu za svoje izmjene
Izmijenite sadržaj lekcija ili primjere koda
Testirajte kod u relevantnim projektnim direktorijima
Pošaljite pull requestove prema smjernicama za doprinos

Za učenike

Forkajte ili klonirajte repozitorij
Krenite redom kroz mape lekcija
Pročitajte README datoteke za svaku lekciju
Riješite pred-lekcijske kvizove na https://ff-quizzes.netlify.app/web/
Prođite kroz primjere koda u mapama lekcija
Riješite zadatke i izazove
Riješite post-lekcijske kvizove

Razvoj uživo

Dokumentacija: Pokrenite docsify serve u korijenu (port 3000)
Quiz aplikacija: Pokrenite npm run dev u mapi quiz-app
Projekti: Koristite VS Code Live Server ekstenziju za HTML projekte
API projekti: Pokrenite npm start u odgovarajućim API mapama

Upute za testiranje

Testiranje Quiz aplikacije

cd quiz-app
npm run lint       # Provjerite za probleme s stilom koda
npm run build      # Provjerite je li izgradnja uspješna

Testiranje Bank API-ja

cd 7-bank-project/api
npm run lint       # Provjerite probleme sa stilom koda
node server.js     # Provjerite pokreće li se poslužitelj bez pogrešaka

Opći pristup testiranju

Ovo je obrazovni repozitorij bez opsežnih automatiziranih testova
Manualno testiranje usmjereno na:
- Primjeri koda rade bez grešaka
- Linkovi u dokumentaciji funkcioniraju ispravno
- Projekti se mogu uspješno izgraditi
- Primjeri slijede najbolje prakse

Provjere prije predaje

Pokrenite npm run lint u mapama koje sadrže package.json
Provjerite valjanost markdown linkova
Testirajte primjere koda u pregledniku ili Node.js-u
Provjerite da prijevodi zadržavaju ispravnu strukturu

Smjernice za stil koda

JavaScript

Koristite modernu ES6+ sintaksu
Slijedite standardne ESLint konfiguracije u projektima
Koristite smisleni nazive varijabli i funkcija za jasnoću učenja
Dodajte komentare koji objašnjavaju koncepte za učenike
Formatirajte pomoću Prettier tamo gdje je konfigurirano

HTML/CSS

Semantički HTML5 elementi
Principi responzivnog dizajna
Jasne konvencije imenovanja klasa
Komentari koji objašnjavaju CSS tehnike za učenike

Python

PEP 8 smjernice za stil
Jasni, obrazovni primjeri koda
Tipizacija gdje je korisno za učenje

Markdown dokumentacija

Jasna hijerarhija naslova
Blokovi koda s označenim jezikom
Linkovi na dodatne resurse
Screenshoti i slike u images/ direktorijima
Alt tekst za slike radi pristupačnosti

Organizacija datoteka

Lekcije numerički označene (1-getting-started-lessons, 2-js-basics itd.)
Svaki projekt ima solution/ i često start/ ili your-work/ direktorije
Slike pohranjenje u lekcijski specifičnim images/ mapama
Prijevodi u strukturi translations/{language-code}/

Izgradnja i implementacija

Implementacija Quiz aplikacije (Azure Static Web Apps)

Quiz-app je konfiguriran za Azure Static Web Apps implementaciju:

cd quiz-app
npm run build      # Stvara dist/ mapu
# Deploya putem GitHub Actions workflowa pri pushanju na main

Konfiguracija Azure Static Web Apps:

Lokacija aplikacije: /quiz-app
Izlazna lokacija: dist
Radni tok: .github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml

Generiranje PDF dokumentacije

npm install                    # Instaliraj docsify-to-pdf
npm run convert               # Generiraj PDF iz docsa

Docsify dokumentacija

npm install -g docsify-cli    # Instalirajte Docsify globalno
docsify serve                 # Poslužite na localhost:3000

Izgradnja specifična za projekte

Svaki projektni direktorij može imati vlastiti postupak izgradnje:

Vue projekti: npm run build stvara produkcijske pakete
Statički projekti: nema koraka izgradnje, datoteke se poslužuju direktno

Smjernice za pull requestove

Format naslova

Koristite jasne, opisne naslove koji navode područje izmjene:

[Quiz-app] Dodaj novi kviz za lekciju X
[Lesson-3] Ispravi tipfeler u terrarium projektu
[Translation] Dodaj španjolski prijevod za lekciju 5
[Docs] Ažuriraj upute za postavljanje

Potrebne provjere

Prije slanja PR-a:

Kvaliteta koda:
- Pokrenite npm run lint u zahvaćenim projektnim mapama
- Ispravite sve linting greške i upozorenja
Verifikacija izgradnje:
- Pokrenite npm run build ako je primjenjivo
- Osigurajte da nema pogrešaka pri izgradnji
Provjera linkova:
- Testirajte sve markdown linkove
- Provjerite ispravnost referenci na slike
Pregled sadržaja:
- Provjerite pravopis i gramatiku
- Osigurajte da su primjeri koda točni i edukativni
- Provjerite da prijevodi zadržavaju izvorno značenje

Zahtjevi za doprinos

Prihvatite Microsoft CLA (automatizirana provjera kod prvog PR-a)
Slijedite Microsoft Open Source Code of Conduct
Pogledajte CONTRIBUTING.md za detaljne smjernice
U opisu PR-a navedite brojeve povezanih issueova ako ih ima

Proces pregleda

PR-ovi pregledavaju održavatelji i zajednica
Prioritet je obrazovna jasnoća
Primjeri koda trebaju slijediti trenutne najbolje prakse
Prijevodi se pregledavaju zbog točnosti i prikladnosti za ciljanu kulturu

Sustav prijevoda

Automatski prijevod

Koristi GitHub Actions s co-op-translator radnim tokom
Automatski prevodi na 50+ jezika
Izvorne datoteke u glavnim direktorijima
Prevedene datoteke u direktorijima translations/{language-code}/

Dodavanje ručnih poboljšanja prijevoda

Pronađite datoteku u translations/{language-code}/
Napravite poboljšanja pri čuvanju strukture
Osigurajte da primjeri koda ostanu funkcionalni
Testirajte lokalizirani kviz sadržaj

Metapodaci prijevoda

Prevedene datoteke uključuju zaglavlje s metapodacima:

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

Debugiranje i rješavanje problema

Uobičajeni problemi

Quiz aplikacija ne uspijeva pokrenuti se:

Provjerite verziju Node.js (preporučeno v14+)
Izbrišite node_modules i package-lock.json, ponovo pokrenite npm install
Provjerite konflikte portova (zadano: Vite koristi port 5173)

API server se ne pokreće:

Provjerite zadovoljava li verzija Node.js minimum (node >=10)
Provjerite koristi li već netko port
Osigurajte da su sve ovisnosti instalirane s npm install

Proširenje preglednika se ne učitava:

Provjerite da je manifest.json ispravno formatiran
Provjerite konzolu preglednika za greške
Slijedite upute za instalaciju specifične za preglednik

Problemi s Python chat projektom:

Provjerite je li paket OpenAI instaliran: pip install openai
Provjerite da je postavljena varijabla okoline GITHUB_TOKEN
Provjerite dozvole pristupa GitHub modelima

Docsify ne poslužuje dokumente:

Instalirajte docsify-cli globalno: npm install -g docsify-cli
Pokrenite iz korijena repozitorija
Provjerite postojanje datoteke docs/_sidebar.md

Savjeti za razvojno okruženje

Koristite VS Code s Live Server ekstenzijom za HTML projekte
Instalirajte ESLint i Prettier ekstenzije za dosljedno formatiranje
Koristite DevTools u pregledniku za debugiranje JavaScript-a
Za Vue projekte instalirajte Vue DevTools ekstenziju za preglednik

Performanse

Velik broj prevedenih datoteka (50+ jezika) čini cjelokupne klonove velikima
Koristite shallow clone ako radite samo na sadržaju: git clone --depth 1
Isključite prijevode iz pretraživanja dok radite na engleskom sadržaju
Postupci izgradnje mogu biti spori pri prvom pokretanju (npm install, Vite build)

Sigurnosni čimbenici

Varijable okoline

API ključevi se nikada ne smiju pohranjivati u repozitorij
Koristite .env datoteke (već u .gitignore)
Dokumentirajte potrebne varijable okoline u README datotekama projekata

Python projekti

Koristite virtualna okruženja: python -m venv venv
Održavajte ovisnosti ažuriranima
GitHub tokeni trebaju imati minimalne potrebne dozvole

Pristup GitHub modelima

Potrebni su Personal Access Tokeni (PAT) za GitHub modele
Tokeni se trebaju pohranjivati kao varijable okoline
Nikada ne commitajte tokene ili vjerodajnice

Dodatne bilješke

Ciljna publika

Potpuni početnici u web razvoju
Studenti i samouki polaznici
Nastavnici koji koriste plan i program u učionicama
Sadržaj dizajniran za pristupačnost i postupno stjecanje vještina

Obrazovna filozofija

Pristup učenju kroz projekte
Česte provjere znanja (kvizovi)
Praktične vježbe kodiranja
Primjeri iz stvarnog svijeta
Fokus na osnove prije okvira

Održavanje repozitorija

Aktivna zajednica učenika i suradnika
Redovna ažuriranja ovisnosti i sadržaja
Problemi i rasprave nadgledaju održavatelji
Automatska ažuriranja prijevoda putem GitHub Actions

Povezani resursi

Microsoft Learn moduli
Student Hub resursi
GitHub Copilot preporučeno za učenike
Dodatni tečajevi: Generativni AI, znanost o podacima, ML, IoT planovi i programi

Rad s određenim projektima

Za detaljne upute o pojedinačnim projektima pogledajte README datoteke u:

quiz-app/README.md - Vue 3 aplikacija za kvizove
7-bank-project/README.md - Bankovna aplikacija s autentifikacijom
5-browser-extension/README.md - Razvoj proširenja preglednika
6-space-game/README.md - Razvoj igre na canvasu
9-chat-project/README.md - AI pomoćnik za chat

Struktura monorepoa

Iako nije tradicionalni monorepo, ovaj repozitorij sadrži više neovisnih projekata:

Svaka lekcija je samostalna
Projekti ne dijele ovisnosti
Radite na pojedinačnim projektima bez utjecaja na druge
Klonirajte cijeli repozitorij za cjelokupno iskustvo plana i programa

Izjava o odricanju od odgovornosti:
Ovaj je dokument preveden pomoću AI usluge prevođenja Co-op Translator. Iako nastojimo postići točnost, imajte na umu da automatski prijevodi mogu sadržavati greške ili netočnosti. Izvorni dokument na izvornom jeziku treba se smatrati autoritativnim izvorištem. Za kritične informacije preporučuje se profesionalni ljudski prijevod. Nismo odgovorni za bilo kakva nesporazuma ili pogrešna tumačenja koja proizlaze iz korištenja ovog prijevoda.

13 KiB Raw Permalink Blame History