14 KiB

Raw Permalink Blame History

AGENTS.md

Prezentare generală a proiectului

Acesta este un depozit curricular educațional pentru predarea fundamentelor dezvoltării web începătorilor. Curriculumul este un curs cuprinzător de 12 săptămâni, dezvoltat de Microsoft Cloud Advocates, care include 24 de lecții practice acoperind JavaScript, CSS și HTML.

Componente cheie

Conținut educațional: 24 de lecții structurate, organizate în module bazate pe proiecte
Proiecte practice: Terrarium, Joc de tastare, Extensie de browser, Joc spațial, Aplicație bancară, Editor de cod și Asistent chat AI
Chestionare interactive: 48 de chestionare cu câte 3 întrebări fiecare (evaluări pre/post-lectie)
Suport multilingv: Traduceri automate în peste 50 de limbi prin GitHub Actions
Tehnologii: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (pentru proiecte AI)

Arhitectură

Depozit educațional cu structură bazată pe lecții
Fiecare folder de lecție conține README, exemple de cod și soluții
Proiecte independente în directoare separate (quiz-app, proiecte diverse de lecții)
Sistem de traducere folosind GitHub Actions (co-op-translator)
Documentație servită prin Docsify și disponibilă ca PDF

Comenzi de configurare

Acest depozit este destinat în principal pentru consumul conținutului educațional. Pentru a lucra cu proiecte specifice:

Configurare principală a depozitului

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

Configurare Quiz App (Vue 3 + Vite)

cd quiz-app
npm install
npm run dev        # Pornește serverul de dezvoltare
npm run build      # Construiește pentru producție
npm run lint       # Rulează ESLint

API proiect bancar (Node.js + Express)

cd 7-bank-project/api
npm install
npm start          # Pornește serverul API
npm run lint       # Rulează ESLint
npm run format     # Formatează cu Prettier

Proiecte extensie de browser

cd 5-browser-extension/solution
npm install
# Urmați instrucțiunile specifice browserului pentru încărcarea extensiilor

Proiecte joc spațial

cd 6-space-game/solution
npm install
# Deschide index.html în browser sau folosește Live Server

Proiect chat (backend Python)

cd 9-chat-project/solution/backend/python
pip install openai
# Setează variabila de mediu GITHUB_TOKEN
python api.py

Flux de dezvoltare

Pentru contribuitorii de conținut

Fork-uiți depozitul în contul dvs. GitHub
Clonați fork-ul local
Creați un nou branch pentru modificările dvs.
Modificați conținutul lecțiilor sau exemplele de cod
Testați orice modificare de cod în directoarele proiectelor relevante
Trimiteți pull request-uri urmând ghidurile de contribuție

Pentru cursanți

Faceți fork sau clonați depozitul
Navigați secvențial prin directoarele lecțiilor
Citiți fișierele README pentru fiecare lecție
Completați chestionarele pre-lectie la https://ff-quizzes.netlify.app/web/
Parcurgeți exemplele de cod din folderele lecțiilor
Finalizați temele și provocările
Susțineți chestionarele post-lectie

Dezvoltare live

Documentație: Rulați docsify serve în rădăcină (port 3000)
Quiz App: Rulați npm run dev în directorul quiz-app
Proiecte: Folosiți extensia VS Code Live Server pentru proiectele HTML
Proiecte API: Rulați npm start în directoarele specifice API

Instrucțiuni de testare

Testare Quiz App

cd quiz-app
npm run lint       # Verifică problemele de stil în cod
npm run build      # Verifică dacă compilarea reușește

Testare API bancar

cd 7-bank-project/api
npm run lint       # Verifică problemele de stil de cod
node server.js     # Verifică dacă serverul pornește fără erori

Abordare generală de testare

Acesta este un depozit educațional fără teste automate comprehensive
Testarea manuală se concentrează pe:
- Rularea exemplelor de cod fără erori
- Funcționarea corectă a linkurilor din documentație
- Complectarea cu succes a compilărilor proiectelor
- Exemplele urmează cele mai bune practici

Verificări înainte de trimitere

Rulați npm run lint în directoarele cu package.json
Verificați validitatea linkurilor markdown
Testați exemplele de cod în browser sau Node.js
Verificați dacă traducerile păstrează structura corectă

Ghid de stil de cod

JavaScript

Folosiți sintaxa modernă ES6+
Respectați configurațiile ESLint standard furnizate în proiecte
Folosiți nume de variabile și funcții semnificative pentru claritatea educațională
Adăugați comentarii explicative pentru concepte pentru cursanți
Formatați folosind Prettier acolo unde este configurat

HTML/CSS

Elemente semantice HTML5
Principii de design responsive
Convenții clare de denumire a claselor
Comentarii explicative pentru tehnici CSS pentru cursanți

Python

Ghiduri de stil PEP 8
Exemple clare și educaționale de cod
Tipări de tip unde sunt utile pentru învățare

Documentație Markdown

Ierarhie clară a titlurilor
Blocuri de cod cu specificare a limbajului
Linkuri către resurse suplimentare
Capturi de ecran și imagini în directoarele images/
Text alternativ pentru imagini pentru accesibilitate

Organizarea fișierelor

Lecții numerotate secvențial (1-getting-started-lessons, 2-js-basics etc.)
Fiecare proiect are directoare solution/ și adesea start/ sau your-work/
Imaginile sunt stocate în foldere images/ specifice lecțiilor
Traducerile sunt în structura translations/{cod-limbă}/

Compilare și implementare

Implementare Quiz App (Azure Static Web Apps)

quiz-app este configurat pentru implementarea Azure Static Web Apps:

cd quiz-app
npm run build      # Creează folderul dist/
# Publică prin fluxul de lucru GitHub Actions la împingerea pe main

Configurarea Azure Static Web Apps:

Locație aplicație: /quiz-app
Locație output: dist
Flux de lucru: .github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml

Generare PDF documentație

npm install                    # Instalează docsify-to-pdf
npm run convert               # Generează PDF din docs

Documentație Docsify

npm install -g docsify-cli    # Instalează Docsify global
docsify serve                 # Servește pe localhost:3000

Construiri specifice proiectelor

Fiecare director de proiect poate avea propriul proces de compilare:

Proiecte Vue: npm run build creează bundle-uri de producție
Proiecte statice: Fără pas de build, se servesc fișierele direct

Ghid pentru pull request-uri

Format titlu

Folosiți titluri clare, descriptive, indicând aria de schimbare:

[Quiz-app] Adăugare quiz nou pentru lecția X
[Lesson-3] Corectare greșeală de tipar în proiectul terrarium
[Translation] Adăugare traducere în spaniolă pentru lecția 5
[Docs] Actualizare instrucțiuni de configurare

Verificări necesare

Înainte de trimiterea PR:

Calitatea codului:
- Rulați npm run lint în directoarele proiectului afectat
- Remediați toate erorile și avertismentele de lint
Verificarea build-ului:
- Rulați npm run build dacă este cazul
- Asigurați-vă că nu există erori de compilare
Validare link-uri:
- Testați toate linkurile markdown
- Verificați referințele imaginilor
Revizuirea conținutului:
- Corectați ortografia și gramatica
- Asigurați-vă că exemplele de cod sunt corecte și educaționale
- Verificați dacă traducerile păstrează sensul original

Cerințe de contribuție

Acceptați CLA Microsoft (verificare automată la primul PR)
Respectați Codul de conduită Microsoft Open Source
Consultați CONTRIBUTING.md pentru ghiduri detaliate
Referiți numere de issue în descrierea PR-ului dacă este cazul

Proces de revizuire

PR-urile sunt revizuite de către mentori și comunitate
Claritatea educațională este prioritară
Exemplele de cod ar trebui să urmeze cele mai bune practici actuale
Traducerile sunt revizuite pentru acuratețe și adecvare culturală

Sistem de traducere

Traducere automată

Folosește GitHub Actions cu flux de lucru co-op-translator
Traduce automat în peste 50 de limbi
Fișiere sursă în directoarele principale
Fișiere traduse în directoarele translations/{cod-limba}/

Adăugarea de îmbunătățiri manuale la traduceri

Localizați fișierul în translations/{cod-limba}/
Faceți îmbunătățiri păstrând structura
Asigurați-vă că exemplele de cod rămân funcționale
Testați orice conținut localizat pentru chestionare

Metadata traducerii

Fișierele traduse includ un antet metadata:

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

Depanare și rezolvare probleme

Probleme comune

Quiz app nu pornește:

Verificați versiunea Node.js (recomandat v14+)
Ștergeți node_modules și package-lock.json, rulați din nou npm install
Verificați conflictele de port (implicit: Vite folosește portul 5173)

Serverul API nu pornește:

Verificați dacă versiunea Node.js este minim (node >=10)
Verificați dacă portul este deja utilizat
Asigurați-vă că toate dependențele sunt instalate cu npm install

Extensia browser nu se încarcă:

Verificați dacă manifest.json este corect formatat
Verificați consola browserului pentru erori
Urmați instrucțiunile specifice browserului pentru instalarea extensiei

Probleme proiect chat Python:

Asigurați-vă că pachetul OpenAI este instalat: pip install openai
Verificați dacă variabila de mediu GITHUB_TOKEN este setată
Verificați permisiunile de acces GitHub Models

Docsify nu servește documentația:

Instalați docsify-cli global: npm install -g docsify-cli
Rulați din directorul rădăcină al depozitului
Verificați că există docs/_sidebar.md

Sfaturi pentru mediul de dezvoltare

Folosiți VS Code cu extensia Live Server pentru proiectele HTML
Instalați extensiile ESLint și Prettier pentru formatare consistentă
Folosiți DevTools din browser pentru depanarea JavaScript
Pentru proiectele Vue, instalați extensia Vue DevTools pentru browser

Considerații de performanță

Numărul mare de fișiere traduse (50+ limbi) face clonele complete mari
Folosiți clone shallow dacă lucrați doar cu conținut: git clone --depth 1
Excludeți traducerile din căutări când lucrați cu conținutul în engleză
Procesele de build pot fi lente la prima rulare (npm install, build Vite)

Considerații de securitate

Variabile de mediu

Cheile API nu trebuie niciodată să fie comise în depozit
Folosiți fișiere .env (explicit ignorate în .gitignore)
Documentați variabilele de mediu necesare în README-urile proiectelor

Proiecte Python

Folosiți medii virtuale: python -m venv venv
Mențineți dependențele actualizate
Token-urile GitHub trebuie să aibă permisiuni minime necesare

Acces GitHub Models

Sunt necesare token-uri de acces personal (PAT) pentru GitHub Models
Tokenurile trebuie stocate ca variabile de mediu
Nu comiteți niciodată tokenurile sau credențialele

Note suplimentare

Public țintă

Începători compleți în dezvoltarea web
Studenți și autodidacți
Profesori care folosesc curriculumul în săli de clasă
Conținut creat pentru accesibilitate și dezvoltare graduală a abilităților

Filosofia educațională

Abordare bazată pe învățare prin proiecte
Verificări frecvente ale cunoștințelor (chestionare)
Exerciții practice de codare
Exemple de aplicații din lumea reală
Accent pe fundamente înainte de framework-uri

Mentenanța depozitului

Comunitate activă de cursanți și contribuitori
Actualizări regulate ale dependințelor și conținutului
Probleme și discuții monitorizate de mentori
Actualizări automate ale traducerilor prin GitHub Actions

Resurse conexe

Module Microsoft Learn
Resurse Student Hub
GitHub Copilot recomandat pentru cursanți
Cursuri suplimentare: AI generativ, Data Science, ML, curriculum IoT disponibile

Lucrul cu proiecte specifice

Pentru instrucțiuni detaliate despre proiectele individuale consultați fișierele README din:

quiz-app/README.md - aplicație quiz Vue 3
7-bank-project/README.md - aplicație bancară cu autentificare
5-browser-extension/README.md - dezvoltare extensie browser
6-space-game/README.md - dezvoltare joc canvas
9-chat-project/README.md - proiect asistent chat AI

Structura monorepo

Deși nu este un monorepo tradițional, acest depozit conține mai multe proiecte independente:

Fiecare lecție este auto-conținută
Proiectele nu împart dependențe
Se poate lucra pe proiecte individuale fără a afecta altele
Clonați întregul depozit pentru experiența completă a curriculumului

Declinare a responsabilității:
Acest document a fost tradus folosind serviciul de traducere AI Co-op Translator. În timp ce ne străduim pentru acuratețe, vă rugăm să fiți conștienți că traducerile automate pot conține erori sau inexactități. Documentul original în limba sa nativă trebuie considerat sursa autoritară. Pentru informații critice, se recomandă traducerea profesională realizată de un specialist uman. Nu ne asumăm răspunderea pentru eventualele neînțelegeri sau interpretări greșite apărute în urma utilizării acestei traduceri.

14 KiB Raw Permalink Blame History