14 KiB

Raw Permalink Blame History Unescape Escape

AGENTS.md

Panoramica del Progetto

Questo è un repository di curriculum educativo per l'insegnamento delle basi dello sviluppo web ai principianti. Il curriculum è un corso completo di 12 settimane sviluppato dai Microsoft Cloud Advocates, che include 24 lezioni pratiche su JavaScript, CSS e HTML.

Componenti Chiave

Contenuto Educativo: 24 lezioni strutturate organizzate in moduli basati su progetti
Progetti Pratici: Terrarium, Gioco di Digitazione, Estensione Browser, Gioco Spaziale, App Bancaria, Editor di Codice e Assistente Chat AI
Quiz Interattivi: 48 quiz con 3 domande ciascuno (valutazioni pre/post-lezione)
Supporto Multilingue: Traduzioni automatiche per oltre 50 lingue tramite GitHub Actions
Tecnologie: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (per progetti AI)

Architettura

Repository educativo con struttura basata sulle lezioni
Ogni cartella di lezione contiene README, esempi di codice e soluzioni
Progetti standalone in directory separate (quiz-app, vari progetti di lezione)
Sistema di traduzione tramite GitHub Actions (co-op-translator)
Documentazione servita tramite Docsify e disponibile in PDF

Comandi di Configurazione

Questo repository è principalmente per il consumo di contenuti educativi. Per lavorare su progetti specifici:

Configurazione Principale del Repository

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

Configurazione Quiz App (Vue 3 + Vite)

cd quiz-app
npm install
npm run dev        # Avvia il server di sviluppo
npm run build      # Compila per la produzione
npm run lint       # Esegui ESLint

API del Progetto Bancario (Node.js + Express)

cd 7-bank-project/api
npm install
npm start          # Avvia il server API
npm run lint       # Esegui ESLint
npm run format     # Formatta con Prettier

Progetti Estensione Browser

cd 5-browser-extension/solution
npm install
# Seguire le istruzioni specifiche del browser per il caricamento delle estensioni

Progetti Gioco Spaziale

cd 6-space-game/solution
npm install
# Apri index.html nel browser o usa Live Server

Progetto Chat (Backend Python)

cd 9-chat-project/solution/backend/python
pip install openai
# Imposta la variabile d'ambiente GITHUB_TOKEN
python api.py

Flusso di Lavoro di Sviluppo

Per i Collaboratori di Contenuti

Effettua il fork del repository nel tuo account GitHub
Clona il tuo fork localmente
Crea un nuovo branch per le tue modifiche
Modifica il contenuto delle lezioni o gli esempi di codice
Testa le modifiche al codice nelle directory dei progetti rilevanti
Invia pull request seguendo le linee guida di contributo

Per gli Studenti

Fai fork o clona il repository
Naviga sequenzialmente nelle directory delle lezioni
Leggi i file README di ogni lezione
Completa i quiz pre-lezione su https://ff-quizzes.netlify.app/web/
Lavora sugli esempi di codice nelle cartelle delle lezioni
Completa compiti e sfide
Esegui i quiz post-lezione

Sviluppo in Tempo Reale

Documentazione: Esegui docsify serve nella root (porta 3000)
Quiz App: Esegui npm run dev nella directory quiz-app
Progetti: Usa l'estensione Live Server di VS Code per progetti HTML
Progetti API: Esegui npm start nelle directory API corrispondenti

Istruzioni per il Testing

Testing Quiz App

cd quiz-app
npm run lint       # Controlla problemi di stile del codice
npm run build      # Verifica che la compilazione abbia successo

Testing API Bancaria

cd 7-bank-project/api
npm run lint       # Controlla problemi di stile del codice
node server.js     # Verifica che il server si avvii senza errori

Approccio Generale al Testing

Questo è un repository educativo senza test automatici completi
Il testing manuale si concentra su:
- Esecuzione senza errori degli esempi di codice
- Correttezza dei link nella documentazione
- Completamento con successo delle build dei progetti
- Esempi che seguono le best practice

Controlli Pre-Invio

Esegui npm run lint nelle directory con package.json
Verifica che i link markdown siano validi
Testa gli esempi di codice in browser o Node.js
Controlla che le traduzioni mantengano la struttura corretta

Linee Guida sullo Stile del Codice

JavaScript

Usa sintassi moderna ES6+
Segui le configurazioni standard ESLint fornite nei progetti
Usa nomi di variabili e funzioni significativi per chiarezza educativa
Aggiungi commenti per spiegare concetti agli studenti
Formattta usando Prettier dove configurato

HTML/CSS

Elementi semantici HTML5
Principi di design responsive
Convenzioni chiare di denominazione delle classi
Commenti che spiegano tecniche CSS per gli studenti

Python

Linee guida di stile PEP 8
Esempi di codice chiari ed educativi
Suggerimenti di tipo dove utili per l’apprendimento

Documentazione Markdown

Gerarchia chiara delle intestazioni
Blocchi di codice con specifica del linguaggio
Link a risorse aggiuntive
Screenshot e immagini nelle cartelle images/
Testo alternativo per le immagini per accessibilità

Organizzazione dei File

Lezioni numerate sequenzialmente (1-getting-started-lessons, 2-js-basics, ecc.)
Ogni progetto ha directory solution/ e spesso anche start/ o your-work/
Immagini archiviate nelle cartelle images/ specifiche di ogni lezione
Traduzioni nella struttura translations/{language-code}/

Build e Deploy

Distribuzione Quiz App (Azure Static Web Apps)

La quiz-app è configurata per il deployment su Azure Static Web Apps:

cd quiz-app
npm run build      # Crea la cartella dist/
# Distribuisce tramite il flusso di lavoro GitHub Actions al push su main

Configurazione Azure Static Web Apps:

Posizione dell’app: /quiz-app
Posizione output: dist
Workflow: .github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml

Generazione PDF della Documentazione

npm install                    # Installa docsify-to-pdf
npm run convert               # Genera PDF da docs

Documentazione Docsify

npm install -g docsify-cli    # Installa Docsify globalmente
docsify serve                 # Servi su localhost:3000

Build Specifici dei Progetti

Ogni directory progetto può avere un proprio processo di build:

Progetti Vue: npm run build crea bundle per produzione
Progetti statici: Nessun passaggio build, i file sono serviti direttamente

Linee Guida per le Pull Request

Formato del Titolo

Usa titoli chiari e descrittivi che indichino l’area di modifica:

[Quiz-app] Aggiungi nuovo quiz per la lezione X
[Lesson-3] Correzione refusi nel progetto terrarium
[Translation] Aggiunta traduzione spagnola per la lezione 5
[Docs] Aggiornamento istruzioni di configurazione

Controlli Richiesti

Prima di inviare una PR:

Qualità del Codice:
- Esegui npm run lint nelle directory progetto interessate
- Risolvi tutti gli errori e avvertimenti di lint
Verifica Build:
- Esegui npm run build se applicabile
- Assicurati che non ci siano errori di build
Validazione Link:
- Testa tutti i link markdown
- Verifica che i riferimenti alle immagini funzionino
Revisione del Contenuto:
- Correggi ortografia e grammatica
- Assicurati che gli esempi di codice siano corretti ed educativi
- Verifica che le traduzioni mantengano il significato originale

Requisiti per il Contributo

Accettare il CLA Microsoft (controllo automatico alla prima PR)
Seguire il Codice di Condotta Open Source Microsoft
Consultare CONTRIBUTING.md per linee guida dettagliate
Fare riferimento ai numeri degli issue nella descrizione della PR se applicabile

Processo di Revisione

Le PR sono revisionate da mantenitori e comunità
La chiarezza educativa è prioritaria
Gli esempi di codice devono seguire le best practice attuali
Le traduzioni sono revisionate per precisione e adeguatezza culturale

Sistema di Traduzione

Traduzione Automatica

Usa GitHub Actions con il workflow co-op-translator
Traduce automaticamente in oltre 50 lingue
File sorgente nelle directory principali
File tradotti in translations/{language-code}/

Aggiunta di Miglioramenti Manuali alle Traduzioni

Individua il file in translations/{language-code}/
Effettua miglioramenti preservando la struttura
Assicurati che gli esempi di codice rimangano funzionanti
Testa eventuale contenuto quiz localizzato

Metadata delle Traduzioni

I file tradotti includono header di metadata:

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

Debug e Risoluzione Problemi

Problemi Comuni

Quiz app non si avvia:

Verifica versione Node.js (consigliato v14+)
Elimina node_modules e package-lock.json, esegui di nuovo npm install
Controlla conflitti di porta (default: Vite usa porta 5173)

Server API non si avvia:

Verifica versione Node.js minima (node >=10)
Controlla che la porta non sia già utilizzata
Assicurati che tutte le dipendenze siano installate con npm install

Estensione browser non si carica:

Verifica che manifest.json sia formattato correttamente
Controlla la console del browser per errori
Segui le istruzioni specifiche di installazione per il browser

Problemi progetto chat Python:

Assicurati che il pacchetto OpenAI sia installato: pip install openai
Verifica che la variabile ambiente GITHUB_TOKEN sia impostata
Controlla i permessi d'accesso ai modelli GitHub

Docsify non serve la documentazione:

Installa docsify-cli globalmente: npm install -g docsify-cli
Avvia dal root del repository
Verifica che docs/_sidebar.md esista

Consigli per l’Ambiente di Sviluppo

Usa VS Code con l’estensione Live Server per i progetti HTML
Installa le estensioni ESLint e Prettier per formattazione coerente
Usa DevTools del browser per il debug di JavaScript
Per progetti Vue, installa l’estensione Vue DevTools per browser

Considerazioni sulle Prestazioni

L’alto numero di file tradotti (oltre 50 lingue) rende le clone complete molto grandi
Usa clone superficiale se lavori solo sul contenuto: git clone --depth 1
Escludi le traduzioni dalle ricerche quando lavori su contenuti in inglese
I processi di build possono essere lenti al primo avvio (npm install, build Vite)

Considerazioni di Sicurezza

Variabili d’Ambiente

Le chiavi API non devono mai essere committate nel repository
Usa file .env (già presenti in .gitignore)
Documenta le variabili ambiente richieste nei README dei progetti

Progetti Python

Usa ambienti virtuali: python -m venv venv
Mantieni aggiornate le dipendenze
I token GitHub devono avere i permessi minimi necessari

Accesso ai Modelli GitHub

Sono richiesti Personal Access Token (PAT) per i modelli GitHub
I token devono essere conservati come variabili ambiente
Mai committare token o credenziali

Note Aggiuntive

Pubblico Target

Principianti completi nello sviluppo web
Studenti e autoapprendenti
Insegnanti che usano il curriculum in aula
I contenuti sono progettati per accessibilità e sviluppo graduale delle competenze

Filosofia Educativa

Approccio di apprendimento basato su progetti
Controlli di conoscenza frequenti (quiz)
Esercizi pratici di programmazione
Esempi di applicazioni reali
Focus sulle basi prima dei framework

Manutenzione del Repository

Comunità attiva di studenti e collaboratori
Aggiornamenti regolari di dipendenze e contenuti
Issue e discussioni monitorate dai mantenitori
Aggiornamenti delle traduzioni automatizzati tramite GitHub Actions

Risorse Correlate

Moduli Microsoft Learn
Risorse Student Hub
GitHub Copilot consigliato per gli studenti
Corsi aggiuntivi: Generative AI, Data Science, ML, curricula IoT disponibili

Lavorare con Progetti Specifici

Per istruzioni dettagliate sui singoli progetti, riferirsi ai file README in:

quiz-app/README.md - Applicazione quiz Vue 3
7-bank-project/README.md - Applicazione bancaria con autenticazione
5-browser-extension/README.md - Sviluppo estensione browser
6-space-game/README.md - Sviluppo gioco con canvas
9-chat-project/README.md - Progetto assistente chat AI

Struttura Monorepo

Pur non essendo un monorepo tradizionale, questo repository contiene molteplici progetti indipendenti:

Ogni lezione è autonoma
I progetti non condividono dipendenze
Lavorare su progetti individuali senza influenzare gli altri
Clonare l’intero repo per l’esperienza completa del curriculum

Dichiarazione di esclusione di responsabilità:
Questo documento è stato tradotto utilizzando il servizio di traduzione automatica 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 nativa deve essere considerato la fonte autorevole. Per informazioni critiche, si raccomanda una traduzione professionale effettuata da un umano. Non siamo responsabili per eventuali incomprensioni o interpretazioni errate derivanti dall’uso di questa traduzione.

14 KiB Raw Permalink Blame History Unescape Escape