13 KiB

Raw Permalink Blame History Unescape Escape

AGENTS.md

Panoramica del Progetto

Questo è 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.

Componenti Chiave

Contenuti Educativi: 24 lezioni strutturate organizzate in moduli basati su progetti
Progetti Pratici: Terrario, 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 lezione contiene README, esempi di codice e soluzioni
Progetti indipendenti in directory separate (quiz-app, vari progetti delle lezioni)
Sistema di traduzione usando GitHub Actions (co-op-translator)
Documentazione servita tramite Docsify e disponibile in PDF

Comandi di Setup

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

Setup Principale del Repository

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

Setup 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 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     # Format con Prettier

Progetti Estensioni 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 Sviluppo

Per i Contributori di Contenuti

Fai il fork del repository sul tuo account GitHub
Clona il tuo fork localmente
Crea un nuovo branch per le tue modifiche
Apporta modifiche ai contenuti della lezione o agli esempi di codice
Testa ogni modifica 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 per 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
Sostieni i quiz post-lezione

Sviluppo Live

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

Istruzioni per i Test

Test Quiz App

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

Test 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 ai Test

Questo è un repository educativo senza test automatizzati completi
Il testing manuale si concentra su:
- Gli esempi di codice funzionano senza errori
- I link nella documentazione sono funzionanti
- Le build dei progetti completano con successo
- Gli esempi rispettano 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 per lo Stile del Codice

JavaScript

Usa sintassi moderna ES6+
Segui le configurazioni ESLint standard fornite nei progetti
Usa nomi significativi per variabili e funzioni per chiarezza didattica
Aggiungi commenti che spiegano i concetti per gli studenti
Formattta usando Prettier dove configurato

HTML/CSS

Elementi semantici HTML5
Principi di design responsivo
Convenzioni chiare per la nomenclatura delle classi
Commenti che spiegano le tecniche CSS per gli studenti

Python

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

Documentazione Markdown

Gerarchia chiara delle intestazioni
Blocchi di codice con specifica 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 start/ o your-work/
Immagini archiviate nelle cartelle images/ specifiche della lezione
Traduzioni in struttura translations/{language-code}/

Build e Deployment

Deployment 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/
# Esegue il deploy tramite workflow di GitHub Actions al push su main

Configurazione Azure Static Web Apps:

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

Generazione PDF 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 per Progetto

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

Progetti Vue: npm run build crea bundle di produzione
Progetti statici: nessun passaggio di build, servire i file direttamente

Linee Guida per le Pull Request

Formato del Titolo

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

[Quiz-app] Aggiunta nuovo quiz per la lezione X
[Lesson-3] Correzione errore di battitura nel progetto terrario
[Translation] Aggiunta traduzione spagnola per la lezione 5
[Docs] Aggiornate istruzioni di setup

Controlli Richiesti

Prima di inviare una PR:

Qualità del Codice:
- Esegui npm run lint nelle directory dei progetti interessati
- Correggi tutti errori e avvisi 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 riferimenti alle immagini
Revisione Contenuti:
- Controllo ortografia e grammatica
- Assicurati che gli esempi di codice siano corretti e didattici
- Verifica che le traduzioni mantengano il significato originale

Requisiti di Contributo

Accetta la Microsoft CLA (verifica automatica alla prima PR)
Segui il Codice di Condotta Open Source Microsoft
Consulta CONTRIBUTING.md per dettagli
Riferisci numeri di issue nella descrizione PR se appropriato

Processo di Revisione

Le PR sono revisionate da maintainer e community
Si dà priorità alla chiarezza didattica
Gli esempi di codice devono seguire le migliori pratiche correnti
Le traduzioni sono riviste per accuratezza e adeguatezza culturale

Sistema di Traduzione

Traduzione Automatica

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

Aggiungere Miglioramenti Manuali

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

Metadata Traduzione

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:

Controlla versione Node.js (consigliata v14+)
Cancella 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 che versione Node.js sia almeno (node >=10)
Controlla se la porta è già in uso
Assicurati che tutte le dipendenze siano installate con npm install

Estensione browser non si carica:

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

Problemi con 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 di accesso ai Modelli GitHub

Docsify non serve la documentazione:

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

Consigli Ambiente di Sviluppo

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

Considerazioni sulle Prestazioni

Gran numero di file tradotti (oltre 50 lingue) rende il clone completo pesante
Usa clone shallow se lavori solo sui contenuti: git clone --depth 1
Escludi le traduzioni dalle ricerche quando lavori solo su contenuti in inglese
I processi di build possono essere lenti alla prima esecuzione (npm install, build Vite)

Considerazioni di Sicurezza

Variabili d’Ambiente

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

Progetti Python

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

Accesso Modelli GitHub

Sono richiesti Personal Access Tokens (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 autodidatti
Insegnanti che usano il curriculum in aula
Contenuti progettati per accessibilità e sviluppo graduale delle competenze

Filosofia Educativa

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

Manutenzione del Repository

Comunità attiva di studenti e contributori
Aggiornamenti regolari di dipendenze e contenuti
Issue e discussioni monitorate dai maintainer
Aggiornamenti alle traduzioni automatici via GitHub Actions

Risorse Correlate

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

Lavorare con Progetti Specifici

Per istruzioni dettagliate sui singoli progetti, consulta i 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 basato su Canvas
9-chat-project/README.md - Progetto assistente chat AI

Struttura Monorepo

Sebbene non sia un monorepo tradizionale, questo repository contiene più progetti indipendenti:

Ogni lezione è autonoma
I progetti non condividono dipendenze
Lavora sui singoli progetti senza influenzarne altri
Clona l’intero repo per l’esperienza completa del curriculum

Disclaimer:
Questo documento è stato tradotto utilizzando il servizio di traduzione AI 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.

13 KiB Raw Permalink Blame History Unescape Escape