13 KiB

Raw Permalink Blame History

AGENTS.md

Pregled projekta

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

Ključne komponente

Nastavni sadržaj: 24 strukturirane lekcije organizirane u module temeljene na projektima
Praktični projekti: Terrarij, Igra tipkanja, Proširenje za preglednik, Svemirska igra, Bankarska aplikacija, Code Editor i AI Chat asistent
Interaktivni kvizovi: 48 kvizova sa po 3 pitanja svaki (procjena prije i nakon lekcije)
Višestruka podrška jezika: Automatski prijevodi na 50+ jezika putem GitHub Actions
Tehnologije: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (za AI projekte)

Arhitektura

Edukativni repozitorij sa strukturom baziranom na lekcijama
Svaka mapa lekcije sadrži README, primjere koda i rješenja
Samostalni projekti u posebnim direktorijima (quiz-app, razni projektni lekcijski direktoriji)
Sustav prevođenja pomoću GitHub Actions (co-op-translator)
Dokumentacija poslužena putem Docsify i dostupna kao PDF

Komande za postavljanje

Ovaj repozitorij je primarno namijenjen za konzumaciju edukativnog 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

Bankarski projekt API (Node.js + Express)

cd 7-bank-project/api
npm install
npm start          # Pokreni API poslužitelj
npm run lint       # Pokreni ESLint
npm run format     # Formatiraj s Prettierom

Projekti proširenja za preglednik

cd 5-browser-extension/solution
npm install
# Slijedite upute za učitavanje ekstenzija specifičnih za preglednik

Projekti svemirske igre

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

Chat projekt (Python Backend)

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

Razvojni tijek rada

Za suradnike na sadržaju

Forkajte repozitorij na svoj GitHub račun
Klonirajte svoj fork lokalno
Napravite novu granu za svoje promjene
Izvršite promjene u sadržaju lekcija ili primjerima koda
Testirajte sve izmjene koda u odgovarajućim projektnim direktorijima
Pošaljite pull requestove u skladu s uputama za doprinose

Za učenike

Forkajte ili klonirajte repozitorij
Navigirajte kroz direktorije lekcija redom
Čitajte README datoteke za svaku lekciju
Završite kvizove prije lekcija na https://ff-quizzes.netlify.app/web/
Riješite primjere koda u mapama lekcija
Završite zadatke i izazove
Polažite kvizove nakon lekcija

Živi razvoj

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

Upute za testiranje

Testiranje Quiz aplikacije

cd quiz-app
npm run lint       # Provjeri probleme sa stilom koda
npm run build      # Provjeri uspješnost izgradnje

Testiranje Bank API-ja

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

Opći pristup testiranju

Ovo je edukativni repozitorij bez sveobuhvatnih automatskih testova
Ručno testiranje fokusira se na:
- Primjere koda koji se izvršavaju bez pogrešaka
- Ispravno funkcioniranje linkova u dokumentaciji
- Uspješnu gradnju projekata
- Slijedjenje najboljih praksi u primjerima

Provjere prije slanja

Pokrenite npm run lint u direktorijima s package.json
Provjerite valjanost markdown linkova
Testirajte primjere koda u pregledniku ili Node.js
Provjerite da prijevodi održavaju pravilnu strukturu

Smjernice za stil kodiranja

JavaScript

Koristite modernu ES6+ sintaksu
Slijedite standardne ESLint konfiguracije iz projekata
Koristite smisleno imenovanje varijabli i funkcija radi jasnoće za učenike
Dodajte komentare koji objašnjavaju koncepte
Formatirajte kod koristeći Prettier 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

Pridržavajte se PEP 8 smjernica
Jasni, edukativni primjeri koda
Tipizacije tamo gdje pomažu učenju

Markdown dokumentacija

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

Organizacija datoteka

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

Gradnja i implementacija

Postavljanje Quiz aplikacije (Azure Static Web Apps)

Quiz aplikacija je konfigurirana za implementaciju na Azure Static Web Apps:

cd quiz-app
npm run build      # Stvara mapu dist/
# Implementira putem GitHub Actions workflow-a pri pushanju na main

Konfiguracija Azure Static Web Apps:

Lokacija aplikacije: /quiz-app
Lokacija izlaza: dist
Workflow: .github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml

Generiranje PDF dokumentacije

npm install                    # Instalirajte docsify-to-pdf
npm run convert               # Generirajte PDF iz docsa

Dokumentacija Docsify

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

Gradnje specifične za projekte

Svaki projektni direktorij može imati vlastiti proces gradnje:

Vue projekti: npm run build kreira produkcijske bundleove
Statički projekti: bez koraka gradnje, direktna usluga datoteka

Smjernice za pull requestove

Format naslova

Koristite jasne, opisne naslove koji označavaju područje promjene:

[Quiz-app] Dodaj novi kviz za lekciju X
[Lesson-3] Ispravi tipfelere 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 pogođenim projektnim direktorijima
- Ispravite sve lint greške i upozorenja
Verifikacija gradnje:
- Pokrenite npm run build ako je primjenjivo
- Osigurajte da nema grešaka u gradnji
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 čuvaju izvorno značenje

Zahtjevi za doprinos

Prihvatite Microsoft CLA (automatska provjera pri prvom PR-u)
Slijedite Microsoft Open Source Code of Conduct
Pogledajte CONTRIBUTING.md za detaljne upute
U opisu PR-a navedite brojeve povezanih issuea ako ih ima

Proces pregleda

PR-ove pregledavaju održavatelji i zajednica
Prioritet je jasnoća edukativnog sadržaja
Primjeri koda trebaju slijediti trenutne najbolje prakse
Prijevodi se pregledavaju radi točnosti i kulturne prikladnosti

Sustav prevođenja

Automatizirani prijevod

Koristi GitHub Actions s co-op-translator workflowom
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 pazeći na očuvanje strukture
Osigurajte ispravnost funkcionalnosti primjera koda
Testirajte eventualni lokalizirani sadržaj kvizova

Metapodaci prijevoda

Prevedene datoteke sadrže metapodatkovni header:

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

Otklanjanje pogrešaka i rješavanje problema

Česti problemi

Quiz aplikacija ne želi startati:

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

API server se ne pokreće:

Provjerite zadovoljava li Node.js minimalnu verziju (node >=10)
Provjerite je li port zauzet
Osigurajte da su sve ovisnosti instalirane s npm install

Proširenje za preglednik se ne učitava:

Provjerite ispravnost manifest.json formata
Provjerite konzolu preglednika za greške
Slijedite upute za instalaciju proširenja specifične za preglednik

Problemi s Python chat projektom:

Provjerite je li instaliran paket OpenAI: pip install openai
Provjerite je li GITHUB_TOKEN varijabla okruženja postavljena
Provjerite dozvole pristupa za GitHub Models

Docsify ne poslužuje dokumente:

Instalirajte docsify-cli globalno: npm install -g docsify-cli
Pokrenite iz root direktorija repozitorija
Provjerite postoji li 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 debug JavaScripta
Za Vue projekte instalirajte Vue DevTools ekstenziju za preglednik

Razmatranja performansi

Veliki broj prevedenih datoteka (50+ jezika) uzrokuje velike klonove
Koristite shallow clone ako radite samo na sadržaju: git clone --depth 1
Isključite prijevode iz pretraživanja kad radite na sadržaju na engleskom
Procesi gradnje mogu biti spori pri prvom pokretanju (npm install, Vite build)

Sigurnosna razmatranja

Varijable okruženja

API ključevi se nikad ne bi smjeli komitirati u repozitorij
Koristite .env datoteke (već navedene u .gitignore)
Dokumentirajte potrebne varijable okruženja u README-ima projekata

Python projekti

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

Pristup GitHub Models

Potrebni su Personal Access Tokens (PAT) za GitHub modele
Tokeni trebaju biti pohranjeni kao varijable okruženja
Nikad nemojte komitirati tokene ili vjerodajnice

Dodatne napomene

Ciljana publika

Potpuni početnici u web razvoju
Studenti i samostalni učenici
Nastavnici koji koriste nastavne planove u učionicama
Sadržaj je osmišljen za pristupačnost i postupno stjecanje vještina

Pedagoška filozofija

Pristup učenja baziran na projektima
Česte provjere znanja (kvizovi)
Praktične vježbe kodiranja
Primjeri iz stvarnog svijeta
Fokus na temelje prije okvira

Održavanje repozitorija

Aktivna zajednica učenika i suradnika
Redovne nadogradnje ovisnosti i sadržaja
Problemi i diskusije praćeni od strane održavatelja
Automatska ažuriranja prijevoda putem GitHub Actions

Povezani resursi

Microsoft Learn moduli
Student Hub resursi
Preporučen GitHub Copilot za učenike: GitHub Copilot
Dodatni tečajevi: Generativni AI, Data Science, ML, IoT kurikulumi dostupni

Rad s određenim projektima

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

quiz-app/README.md - Vue 3 aplikacija kviza
7-bank-project/README.md - Bankarska aplikacija s autentikacijom
5-browser-extension/README.md - Razvoj proširenja za preglednik
6-space-game/README.md - Razvoj igre bazirane na canvasu
9-chat-project/README.md - Projekt AI chat asistenta

Struktura Monorepo repozitorija

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

Svaka lekcija je samostalna
Projekti ne dijele ovisnosti
Rad na pojedinačnim projektima bez utjecaja na druge
Klonirajte cijeli repozitorij za potpuno iskustvo nastavnog programa

Odricanje od odgovornosti: Ovaj dokument je preveden pomoću AI usluge za prijevod Co-op Translator. Iako težimo točnosti, molimo imajte na umu da automatski prijevodi mogu sadržavati pogreške ili netočnosti. Izvorni dokument na njegovom izvornom jeziku treba smatrati autoritativnim izvorom. Za važne informacije preporučuje se profesionalni ljudski prijevod. Ne snosimo odgovornost za bilo kakve nesporazume ili kriva tumačenja koja proizlaze iz korištenja ovog prijevoda.

13 KiB Raw Permalink Blame History