14 KiB

Raw Blame History

AGENTS.md

Projektübersicht

Dies ist ein Bildungsrepository, das Grundlagen der Webentwicklung für Anfänger vermittelt. Der Lehrplan ist ein umfassender 12-wöchiger Kurs, der von den Microsoft Cloud Advocates entwickelt wurde und 24 praxisorientierte Lektionen zu JavaScript, CSS und HTML umfasst.

Hauptkomponenten

Bildungsinhalte: 24 strukturierte Lektionen, organisiert in projektbasierte Module
Praktische Projekte: Terrarium, Schreibspiel, Browser-Erweiterung, Weltraumspiel, Banking-App, Code-Editor und KI-Chat-Assistent
Interaktive Quizze: 48 Quizze mit jeweils 3 Fragen (Vor-/Nach-Lektionen-Bewertungen)
Mehrsprachige Unterstützung: Automatische Übersetzungen in über 50 Sprachen via GitHub Actions
Technologien: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (für KI-Projekte)

Architektur

Bildungsrepository mit lektionenbasierter Struktur
Jeder Lektionenordner enthält README, Codebeispiele und Lösungen
Eigenständige Projekte in separaten Verzeichnissen (quiz-app, verschiedene Lektionenprojekte)
Übersetzungssystem mit GitHub Actions (co-op-translator)
Dokumentation wird über Docsify bereitgestellt und ist als PDF verfügbar

Setup-Befehle

Dieses Repository dient hauptsächlich dem Konsum von Bildungsinhalten. Für die Arbeit mit spezifischen Projekten:

Hauptrepository-Setup

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

Quiz-App-Setup (Vue 3 + Vite)

cd quiz-app
npm install
npm run dev        # Start development server
npm run build      # Build for production
npm run lint       # Run ESLint

Bankprojekt-API (Node.js + Express)

cd 7-bank-project/api
npm install
npm start          # Start API server
npm run lint       # Run ESLint
npm run format     # Format with Prettier

Browser-Erweiterungsprojekte

cd 5-browser-extension/solution
npm install
# Follow browser-specific extension loading instructions

Weltraumspiel-Projekte

cd 6-space-game/solution
npm install
# Open index.html in browser or use Live Server

Chat-Projekt (Python-Backend)

cd 9-chat-project/solution/backend/python
pip install openai
# Set GITHUB_TOKEN environment variable
python api.py

Entwicklungsworkflow

Für Inhaltsbeitragende

Forken Sie das Repository in Ihrem GitHub-Konto
Klonen Sie Ihren Fork lokal
Erstellen Sie einen neuen Branch für Ihre Änderungen
Nehmen Sie Änderungen an den Lektioneninhalten oder Codebeispielen vor
Testen Sie alle Codeänderungen in den relevanten Projektverzeichnissen
Reichen Sie Pull-Requests gemäß den Beitragsrichtlinien ein

Für Lernende

Forken oder klonen Sie das Repository
Navigieren Sie nacheinander durch die Lektionenverzeichnisse
Lesen Sie die README-Dateien jeder Lektion
Machen Sie die Vor-Lektionen-Quizze unter https://ff-quizzes.netlify.app/web/
Arbeiten Sie die Codebeispiele in den Lektionenordnern durch
Bearbeiten Sie Aufgaben und Herausforderungen
Machen Sie die Nach-Lektionen-Quizze

Live-Entwicklung

Dokumentation: Führen Sie docsify serve im Root-Verzeichnis aus (Port 3000)
Quiz-App: Führen Sie npm run dev im quiz-app-Verzeichnis aus
Projekte: Verwenden Sie die Live Server-Erweiterung von VS Code für HTML-Projekte
API-Projekte: Führen Sie npm start in den jeweiligen API-Verzeichnissen aus

Testanweisungen

Quiz-App-Test

cd quiz-app
npm run lint       # Check for code style issues
npm run build      # Verify build succeeds

Bank-API-Test

cd 7-bank-project/api
npm run lint       # Check for code style issues
node server.js     # Verify server starts without errors

Allgemeiner Testansatz

Dies ist ein Bildungsrepository ohne umfassende automatisierte Tests
Manuelles Testen konzentriert sich auf:
- Codebeispiele laufen fehlerfrei
- Links in der Dokumentation funktionieren korrekt
- Projekt-Builds werden erfolgreich abgeschlossen
- Beispiele folgen Best Practices

Vorabprüfungen

Führen Sie npm run lint in Verzeichnissen mit package.json aus
Überprüfen Sie, ob Markdown-Links gültig sind
Testen Sie Codebeispiele im Browser oder mit Node.js
Stellen Sie sicher, dass Übersetzungen die richtige Struktur beibehalten

Richtlinien für Code-Stil

JavaScript

Verwenden Sie moderne ES6+ Syntax
Folgen Sie den standardmäßigen ESLint-Konfigurationen in den Projekten
Verwenden Sie aussagekräftige Variablen- und Funktionsnamen für Bildungszwecke
Fügen Sie Kommentare hinzu, die Konzepte für Lernende erklären
Formatieren Sie mit Prettier, wo konfiguriert

HTML/CSS

Semantische HTML5-Elemente
Prinzipien des responsiven Designs
Klare Klassennamen-Konventionen
Kommentare, die CSS-Techniken für Lernende erklären

Python

PEP 8 Stilrichtlinien
Klare, bildungsorientierte Codebeispiele
Typ-Hinweise, wo hilfreich für das Lernen

Markdown-Dokumentation

Klare Überschriftenhierarchie
Codeblöcke mit Sprachspezifikation
Links zu zusätzlichen Ressourcen
Screenshots und Bilder in images/ Verzeichnissen
Alt-Text für Bilder für Barrierefreiheit

Dateiorganisation

Lektionen nummeriert in Reihenfolge (1-getting-started-lessons, 2-js-basics, etc.)
Jedes Projekt hat solution/ und oft start/ oder your-work/ Verzeichnisse
Bilder werden in lektionenspezifischen images/ Ordnern gespeichert
Übersetzungen in translations/{language-code}/ Struktur

Build und Deployment

Quiz-App-Deployment (Azure Static Web Apps)

Die quiz-app ist für die Bereitstellung auf Azure Static Web Apps konfiguriert:

cd quiz-app
npm run build      # Creates dist/ folder
# Deploys via GitHub Actions workflow on push to main

Azure Static Web Apps Konfiguration:

App-Standort: /quiz-app
Ausgabe-Standort: dist
Workflow: .github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml

Dokumentations-PDF-Erstellung

npm install                    # Install docsify-to-pdf
npm run convert               # Generate PDF from docs

Docsify-Dokumentation

npm install -g docsify-cli    # Install Docsify globally
docsify serve                 # Serve on localhost:3000

Projekt-spezifische Builds

Jedes Projektverzeichnis kann seinen eigenen Build-Prozess haben:

Vue-Projekte: npm run build erstellt Produktions-Bundles
Statische Projekte: Kein Build-Schritt, Dateien direkt bereitstellen

Richtlinien für Pull-Requests

Titel-Format

Verwenden Sie klare, beschreibende Titel, die den Bereich der Änderung angeben:

[Quiz-app] Neues Quiz für Lektion X hinzufügen
[Lesson-3] Tippfehler im Terrarium-Projekt beheben
[Translation] Spanische Übersetzung für Lektion 5 hinzufügen
[Docs] Setup-Anweisungen aktualisieren

Erforderliche Prüfungen

Vor dem Einreichen eines PR:

Codequalität:
- Führen Sie npm run lint in den betroffenen Projektverzeichnissen aus
- Beheben Sie alle Linting-Fehler und -Warnungen
Build-Verifizierung:
- Führen Sie npm run build aus, falls zutreffend
- Stellen Sie sicher, dass keine Build-Fehler auftreten
Link-Validierung:
- Testen Sie alle Markdown-Links
- Überprüfen Sie, ob Bildreferenzen funktionieren
Inhaltsprüfung:
- Korrekturlesen auf Rechtschreibung und Grammatik
- Sicherstellen, dass Codebeispiele korrekt und lehrreich sind
- Überprüfen, ob Übersetzungen die ursprüngliche Bedeutung beibehalten

Beitragsanforderungen

Zustimmung zur Microsoft CLA (automatische Prüfung beim ersten PR)
Befolgen Sie den Microsoft Open Source Code of Conduct
Siehe CONTRIBUTING.md für detaillierte Richtlinien
Verweisen Sie auf Issue-Nummern in der PR-Beschreibung, falls zutreffend

Überprüfungsprozess

PRs werden von Maintainer und der Community überprüft
Bildungsverständlichkeit hat Priorität
Codebeispiele sollten aktuellen Best Practices folgen
Übersetzungen werden auf Genauigkeit und kulturelle Angemessenheit geprüft

Übersetzungssystem

Automatische Übersetzung

Verwendet GitHub Actions mit co-op-translator Workflow
Übersetzt automatisch in über 50 Sprachen
Quelldateien in Hauptverzeichnissen
Übersetzte Dateien in translations/{language-code}/ Verzeichnissen

Manuelle Verbesserungen an Übersetzungen hinzufügen

Datei im translations/{language-code}/ Verzeichnis finden
Verbesserungen vornehmen, während die Struktur erhalten bleibt
Sicherstellen, dass Codebeispiele weiterhin funktionieren
Lokalisierte Quiz-Inhalte testen

Übersetzungs-Metadaten

Übersetzte Dateien enthalten einen Metadaten-Header:

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

Debugging und Fehlerbehebung

Häufige Probleme

Quiz-App startet nicht:

Überprüfen Sie die Node.js-Version (v14+ empfohlen)
Löschen Sie node_modules und package-lock.json, führen Sie npm install erneut aus
Überprüfen Sie auf Portkonflikte (Standard: Vite verwendet Port 5173)

API-Server startet nicht:

Überprüfen Sie, ob die Node.js-Version die Mindestanforderungen erfüllt (node >=10)
Überprüfen Sie, ob der Port bereits verwendet wird
Stellen Sie sicher, dass alle Abhängigkeiten mit npm install installiert sind

Browser-Erweiterung lädt nicht:

Überprüfen Sie, ob manifest.json korrekt formatiert ist
Überprüfen Sie die Browser-Konsole auf Fehler
Befolgen Sie die browser-spezifischen Installationsanweisungen für Erweiterungen

Probleme mit Python-Chat-Projekt:

Stellen Sie sicher, dass das OpenAI-Paket installiert ist: pip install openai
Überprüfen Sie, ob die Umgebungsvariable GITHUB_TOKEN gesetzt ist
Überprüfen Sie die Zugriffsberechtigungen für GitHub Models

Docsify dient keine Dokumentation:

Installieren Sie docsify-cli global: npm install -g docsify-cli
Führen Sie es aus dem Root-Verzeichnis des Repositorys aus
Überprüfen Sie, ob docs/_sidebar.md existiert

Tipps zur Entwicklungsumgebung

Verwenden Sie VS Code mit der Live Server-Erweiterung für HTML-Projekte
Installieren Sie ESLint und Prettier-Erweiterungen für konsistente Formatierung
Verwenden Sie die DevTools des Browsers zum Debuggen von JavaScript
Für Vue-Projekte installieren Sie die Vue DevTools Browser-Erweiterung

Leistungserwägungen

Eine große Anzahl übersetzter Dateien (50+ Sprachen) bedeutet, dass vollständige Klone groß sind
Verwenden Sie einen flachen Klon, wenn Sie nur an Inhalten arbeiten: git clone --depth 1
Schließen Sie Übersetzungen von Suchvorgängen aus, wenn Sie an englischen Inhalten arbeiten
Build-Prozesse können beim ersten Lauf langsam sein (npm install, Vite build)

Sicherheitsüberlegungen

Umgebungsvariablen

API-Schlüssel sollten niemals im Repository gespeichert werden
Verwenden Sie .env Dateien (bereits in .gitignore)
Dokumentieren Sie erforderliche Umgebungsvariablen in den Projekt-READMEs

Python-Projekte

Verwenden Sie virtuelle Umgebungen: python -m venv venv
Halten Sie Abhängigkeiten aktuell
GitHub-Token sollten minimale erforderliche Berechtigungen haben

GitHub Models Zugriff

Persönliche Zugriffstoken (PAT) erforderlich für GitHub Models
Token sollten als Umgebungsvariablen gespeichert werden
Token oder Anmeldeinformationen niemals commiten

Zusätzliche Hinweise

Zielgruppe

Vollständige Anfänger in der Webentwicklung
Studenten und Selbstlernende
Lehrer, die den Lehrplan im Unterricht verwenden
Inhalte sind für Barrierefreiheit und schrittweisen Kompetenzaufbau konzipiert

Bildungsphilosophie

Projektbasierter Lernansatz
Häufige Wissensüberprüfungen (Quizze)
Praktische Codierungsübungen
Beispiele aus der realen Welt
Fokus auf Grundlagen vor Frameworks

Repository-Wartung

Aktive Community von Lernenden und Beitragenden
Regelmäßige Updates von Abhängigkeiten und Inhalten
Issues und Diskussionen werden von Maintainer überwacht
Übersetzungsupdates automatisiert über GitHub Actions

Arbeit mit spezifischen Projekten

Für detaillierte Anweisungen zu einzelnen Projekten, siehe die README-Dateien in:

quiz-app/README.md - Vue 3 Quiz-Anwendung
7-bank-project/README.md - Banking-Anwendung mit Authentifizierung
5-browser-extension/README.md - Entwicklung von Browser-Erweiterungen
6-space-game/README.md - Canvas-basiertes Spiel
9-chat-project/README.md - KI-Chat-Assistent-Projekt

Monorepo-Struktur

Obwohl kein traditionelles Monorepo, enthält dieses Repository mehrere unabhängige Projekte:

Jede Lektion ist eigenständig
Projekte teilen keine Abhängigkeiten
Arbeiten Sie an einzelnen Projekten, ohne andere zu beeinflussen
Klonen Sie das gesamte Repository für das vollständige Curriculum-Erlebnis

Haftungsausschluss:
Dieses Dokument wurde mit dem KI-Übersetzungsdienst Co-op Translator übersetzt. Obwohl wir uns um Genauigkeit bemühen, beachten Sie bitte, dass automatisierte Übersetzungen Fehler oder Ungenauigkeiten enthalten können. Das Originaldokument in seiner ursprünglichen Sprache sollte als maßgebliche Quelle betrachtet werden. Für kritische Informationen wird eine professionelle menschliche Übersetzung empfohlen. Wir übernehmen keine Haftung für Missverständnisse oder Fehlinterpretationen, die sich aus der Nutzung dieser Übersetzung ergeben.

14 KiB Raw Blame History