AGENTS.md

1# AGENTS.md
2 
3## Panoramica del Progetto
4 
5Questo è un repository didattico per insegnare le basi dello sviluppo web ai principianti. Il curriculum è un corso completo di 12 settimane sviluppato dai Microsoft Cloud Advocates, con 24 lezioni pratiche che coprono JavaScript, CSS e HTML.
6 
7### Componenti Chiave
8 
9- **Contenuti Educativi**: 24 lezioni strutturate organizzate in moduli basati su progetti
10- **Progetti Pratici**: Terrario, Gioco di Digitazione, Estensione Browser, Gioco Spaziale, App Bancaria, Editor di Codice e Assistente Chat AI
11- **Quiz Interattivi**: 48 quiz con 3 domande ciascuno (valutazioni pre/post lezione)
12- **Supporto Multilingue**: Traduzioni automatiche per oltre 50 lingue tramite GitHub Actions
13- **Tecnologie**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (per progetti AI)
14 
15### Architettura
16 
17- Repository educativo con struttura basata sulle lezioni
18- Ogni cartella lezione contiene README, esempi di codice e soluzioni
19- Progetti indipendenti in directory separate (quiz-app, vari progetti delle lezioni)
20- Sistema di traduzione usando GitHub Actions (co-op-translator)
21- Documentazione servita tramite Docsify e disponibile in PDF
22 
23## Comandi di Setup
24 
25Questo repository è principalmente per il consumo di contenuti educativi. Per lavorare con progetti specifici:
26 
27### Setup Principale del Repository
28 
29```bash
30git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
31cd Web-Dev-For-Beginners
32```
33 
34### Setup Quiz App (Vue 3 + Vite)
35 
36```bash
37cd quiz-app
38npm install
39npm run dev        # Avvia il server di sviluppo
40npm run build      # Compila per la produzione
41npm run lint       # Esegui ESLint
42```
43 
44### API Progetto Bancario (Node.js + Express)
45 
46```bash
47cd 7-bank-project/api
48npm install
49npm start          # Avvia il server API
50npm run lint       # Esegui ESLint
51npm run format     # Format con Prettier
52```
53 
54### Progetti Estensioni Browser
55 
56```bash
57cd 5-browser-extension/solution
58npm install
59# Seguire le istruzioni specifiche del browser per il caricamento delle estensioni
60```
61 
62### Progetti Gioco Spaziale
63 
64```bash
65cd 6-space-game/solution
66npm install
67# Apri index.html nel browser o usa Live Server
68```
69 
70### Progetto Chat (Backend Python)
71 
72```bash
73cd 9-chat-project/solution/backend/python
74pip install openai
75# Imposta la variabile d'ambiente GITHUB_TOKEN
76python api.py
77```
78 
79## Flusso di Lavoro Sviluppo
80 
81### Per i Contributori di Contenuti
82 
831. **Fai il fork del repository** sul tuo account GitHub
842. **Clona il tuo fork** localmente
853. **Crea un nuovo branch** per le tue modifiche
864. Apporta modifiche ai contenuti della lezione o agli esempi di codice
875. Testa ogni modifica al codice nelle directory dei progetti rilevanti
886. Invia pull request seguendo le linee guida di contributo
89 
90### Per gli Studenti
91 
921. Fai fork o clona il repository
932. Naviga sequenzialmente nelle directory delle lezioni
943. Leggi i file README per ogni lezione
954. Completa i quiz pre-lezione su https://ff-quizzes.netlify.app/web/
965. Lavora sugli esempi di codice nelle cartelle delle lezioni
976. Completa compiti e sfide
987. Sostieni i quiz post-lezione
99 
100### Sviluppo Live
101 
102- **Documentazione**: Esegui `docsify serve` nella root (porta 3000)
103- **Quiz App**: Esegui `npm run dev` nella directory quiz-app
104- **Progetti**: Usa l’estensione VS Code Live Server per progetti HTML
105- **Progetti API**: Esegui `npm start` nelle rispettive directory API
106 
107## Istruzioni per i Test
108 
109### Test Quiz App
110 
111```bash
112cd quiz-app
113npm run lint       # Controlla problemi di stile del codice
114npm run build      # Verifica che la compilazione abbia successo
115```
116 
117### Test API Bancaria
118 
119```bash
120cd 7-bank-project/api
121npm run lint       # Controlla problemi di stile del codice
122node server.js     # Verifica che il server si avvii senza errori
123```
124 
125### Approccio Generale ai Test
126 
127- Questo è un repository educativo senza test automatizzati completi
128- Il testing manuale si concentra su:
129  - Gli esempi di codice funzionano senza errori
130  - I link nella documentazione sono funzionanti
131  - Le build dei progetti completano con successo
132  - Gli esempi rispettano le best practice
133 
134### Controlli Pre-Invio
135 
136- Esegui `npm run lint` nelle directory con package.json
137- Verifica che i link markdown siano validi
138- Testa gli esempi di codice in browser o Node.js
139- Controlla che le traduzioni mantengano la struttura corretta
140 
141## Linee Guida per lo Stile del Codice
142 
143### JavaScript
144 
145- Usa sintassi moderna ES6+
146- Segui le configurazioni ESLint standard fornite nei progetti
147- Usa nomi significativi per variabili e funzioni per chiarezza didattica
148- Aggiungi commenti che spiegano i concetti per gli studenti
149- Formattta usando Prettier dove configurato
150 
151### HTML/CSS
152 
153- Elementi semantici HTML5
154- Principi di design responsivo
155- Convenzioni chiare per la nomenclatura delle classi
156- Commenti che spiegano le tecniche CSS per gli studenti
157 
158### Python
159 
160- Linee guida di stile PEP 8
161- Esempi di codice chiari e didattici
162- Suggerimenti di tipo dove utili per l’apprendimento
163 
164### Documentazione Markdown
165 
166- Gerarchia chiara delle intestazioni
167- Blocchi di codice con specifica linguaggio
168- Link a risorse aggiuntive
169- Screenshot e immagini nelle cartelle `images/`
170- Testo alternativo per le immagini per accessibilità
171 
172### Organizzazione dei File
173 
174- Lezioni numerate sequenzialmente (1-getting-started-lessons, 2-js-basics, ecc.)
175- Ogni progetto ha directory `solution/` e spesso `start/` o `your-work/`
176- Immagini archiviate nelle cartelle `images/` specifiche della lezione
177- Traduzioni in struttura `translations/{language-code}/`
178 
179## Build e Deployment
180 
181### Deployment Quiz App (Azure Static Web Apps)
182 
183La quiz-app è configurata per il deployment su Azure Static Web Apps:
184 
185```bash
186cd quiz-app
187npm run build      # Crea la cartella dist/
188# Esegue il deploy tramite workflow di GitHub Actions al push su main
189```
190 
191Configurazione Azure Static Web Apps:
192- **Posizione app**: `/quiz-app`
193- **Cartella output**: `dist`
194- **Workflow**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`
195 
196### Generazione PDF Documentazione
197 
198```bash
199npm install                    # Installa docsify-to-pdf
200npm run convert               # Genera PDF da docs
201```
202 
203### Documentazione Docsify
204 
205```bash
206npm install -g docsify-cli    # Installa Docsify globalmente
207docsify serve                 # Servi su localhost:3000
208```
209 
210### Build Specifici per Progetto
211 
212Ogni directory progetto può avere un proprio processo di build:
213- Progetti Vue: `npm run build` crea bundle di produzione
214- Progetti statici: nessun passaggio di build, servire i file direttamente
215 
216## Linee Guida per le Pull Request
217 
218### Formato del Titolo
219 
220Usa titoli chiari e descrittivi che indicano l’area di modifica:
221- `[Quiz-app] Aggiunta nuovo quiz per la lezione X`
222- `[Lesson-3] Correzione errore di battitura nel progetto terrario`
223- `[Translation] Aggiunta traduzione spagnola per la lezione 5`
224- `[Docs] Aggiornate istruzioni di setup`
225 
226### Controlli Richiesti
227 
228Prima di inviare una PR:
229 
2301. **Qualità del Codice**:
231   - Esegui `npm run lint` nelle directory dei progetti interessati
232   - Correggi tutti errori e avvisi di lint
233 
2342. **Verifica Build**:
235   - Esegui `npm run build` se applicabile
236   - Assicurati che non ci siano errori di build
237 
2383. **Validazione Link**:
239   - Testa tutti i link markdown
240   - Verifica riferimenti alle immagini
241 
2424. **Revisione Contenuti**:
243   - Controllo ortografia e grammatica
244   - Assicurati che gli esempi di codice siano corretti e didattici
245   - Verifica che le traduzioni mantengano il significato originale
246 
247### Requisiti di Contributo
248 
249- Accetta la Microsoft CLA (verifica automatica alla prima PR)
250- Segui il [Codice di Condotta Open Source Microsoft](https://opensource.microsoft.com/codeofconduct/)
251- Consulta [CONTRIBUTING.md](./CONTRIBUTING.md) per dettagli
252- Riferisci numeri di issue nella descrizione PR se appropriato
253 
254### Processo di Revisione
255 
256- Le PR sono revisionate da maintainer e community
257- Si dà priorità alla chiarezza didattica
258- Gli esempi di codice devono seguire le migliori pratiche correnti
259- Le traduzioni sono riviste per accuratezza e adeguatezza culturale
260 
261## Sistema di Traduzione
262 
263### Traduzione Automatica
264 
265- Usa GitHub Actions con workflow co-op-translator
266- Traduce automaticamente in oltre 50 lingue
267- File sorgente nelle directory principali
268- File tradotti in directory `translations/{language-code}/`
269 
270### Aggiungere Miglioramenti Manuali
271 
2721. Trova il file in `translations/{language-code}/`
2732. Apporta miglioramenti preservando la struttura
2743. Assicurati che gli esempi di codice rimangano funzionanti
2754. Testa ogni contenuto quiz localizzato
276 
277### Metadata Traduzione
278 
279I file tradotti includono header di metadata:
280```markdown
281<!--
282CO_OP_TRANSLATOR_METADATA:
283{
284  "original_hash": "...",
285  "translation_date": "...",
286  "source_file": "...",
287  "language_code": "..."
288}
289-->
290```
291 
292## Debug e Risoluzione Problemi
293 
294### Problemi Comuni
295 
296**Quiz app non si avvia**:
297- Controlla versione Node.js (consigliata v14+)
298- Cancella `node_modules` e `package-lock.json`, esegui di nuovo `npm install`
299- Controlla conflitti di porta (default: Vite usa porta 5173)
300 
301**Server API non si avvia**:
302- Verifica che versione Node.js sia almeno (node >=10)
303- Controlla se la porta è già in uso
304- Assicurati che tutte le dipendenze siano installate con `npm install`
305 
306**Estensione browser non si carica**:
307- Verifica che manifest.json sia ben formato
308- Controlla la console del browser per errori
309- Segui le istruzioni specifiche di installazione per il browser
310 
311**Problemi con progetto chat Python**:
312- Assicurati che il pacchetto OpenAI sia installato: `pip install openai`
313- Verifica che la variabile ambiente GITHUB_TOKEN sia impostata
314- Controlla i permessi di accesso ai Modelli GitHub
315 
316**Docsify non serve la documentazione**:
317- Installa docsify-cli globalmente: `npm install -g docsify-cli`
318- Avvia dalla root del repository
319- Verifica che `docs/_sidebar.md` esista
320 
321### Consigli Ambiente di Sviluppo
322 
323- Usa VS Code con estensione Live Server per progetti HTML
324- Installa estensioni ESLint e Prettier per formattazione coerente
325- Usa gli strumenti DevTools del browser per il debug JavaScript
326- Per progetti Vue, installa l’estensione Vue DevTools per browser
327 
328### Considerazioni sulle Prestazioni
329 
330- Gran numero di file tradotti (oltre 50 lingue) rende il clone completo pesante
331- Usa clone shallow se lavori solo sui contenuti: `git clone --depth 1`
332- Escludi le traduzioni dalle ricerche quando lavori solo su contenuti in inglese
333- I processi di build possono essere lenti alla prima esecuzione (npm install, build Vite)
334 
335## Considerazioni di Sicurezza
336 
337### Variabili d’Ambiente
338 
339- Le chiavi API non devono mai essere committate nel repository
340- Usa file `.env` (già in `.gitignore`)
341- Documenta variabili d’ambiente richieste nei README dei progetti
342 
343### Progetti Python
344 
345- Usa ambienti virtuali: `python -m venv venv`
346- Mantieni aggiornate le dipendenze
347- I token GitHub devono avere permessi minimi necessari
348 
349### Accesso Modelli GitHub
350 
351- Sono richiesti Personal Access Tokens (PAT) per i Modelli GitHub
352- I token devono essere conservati come variabili ambiente
353- Mai committare token o credenziali
354 
355## Note Aggiuntive
356 
357### Pubblico Target
358 
359- Principianti completi nello sviluppo web
360- Studenti e autodidatti
361- Insegnanti che usano il curriculum in aula
362- Contenuti progettati per accessibilità e sviluppo graduale delle competenze
363 
364### Filosofia Educativa
365 
366- Approccio basato su progetti
367- Verifiche di apprendimento frequenti (quiz)
368- Esercizi pratici di coding
369- Esempi di applicazioni reali
370- Focus sulle basi prima dei framework
371 
372### Manutenzione del Repository
373 
374- Comunità attiva di studenti e contributori
375- Aggiornamenti regolari di dipendenze e contenuti
376- Issue e discussioni monitorate dai maintainer
377- Aggiornamenti alle traduzioni automatici via GitHub Actions
378 
379### Risorse Correlate
380 
381- [Moduli Microsoft Learn](https://docs.microsoft.com/learn/)
382- [Risorse Student Hub](https://docs.microsoft.com/learn/student-hub/)
383- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) consigliato per gli studenti
384- Corsi aggiuntivi: curricula di IA generativa, Data Science, ML, IoT disponibili
385 
386### Lavorare con Progetti Specifici
387 
388Per istruzioni dettagliate sui singoli progetti, consulta i file README in:
389- `quiz-app/README.md` - Applicazione quiz Vue 3
390- `7-bank-project/README.md` - Applicazione bancaria con autenticazione
391- `5-browser-extension/README.md` - Sviluppo estensione browser
392- `6-space-game/README.md` - Sviluppo gioco basato su Canvas
393- `9-chat-project/README.md` - Progetto assistente chat AI
394 
395### Struttura Monorepo
396 
397Sebbene non sia un monorepo tradizionale, questo repository contiene più progetti indipendenti:
398- Ogni lezione è autonoma
399- I progetti non condividono dipendenze
400- Lavora sui singoli progetti senza influenzarne altri
401- Clona l’intero repo per l’esperienza completa del curriculum
402 
403---
404 
405<!-- CO-OP TRANSLATOR DISCLAIMER START -->
406**Disclaimer**:  
407Questo documento è stato tradotto utilizzando il servizio di traduzione AI [Co-op Translator](https://github.com/Azure/co-op-translator). Pur impegnandoci per l'accuratezza, si prega di notare che le traduzioni automatiche possono contenere errori o imprecisioni. Il documento originale nella sua lingua madre deve essere considerato la fonte autorevole. Per informazioni critiche, si consiglia una traduzione professionale effettuata da un umano. Non siamo responsabili per eventuali incomprensioni o interpretazioni errate derivanti dall'uso di questa traduzione.
408<!-- CO-OP TRANSLATOR DISCLAIMER END -->