13 KiB

Raw Blame History

AGENTS.md

Projektübersicht

Dies ist ein Bildungs-Curriculum-Repository zum Erlernen der Grundlagen der Webentwicklung für Einsteiger. Das Curriculum ist ein umfassender 12-Wochen-Kurs, der von Microsoft Cloud Advocates entwickelt wurde und 24 praxisorientierte Lektionen zu JavaScript, CSS und HTML enthält.

Hauptkomponenten

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

Architektur

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

Setup-Befehle

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

Haupt-Repository-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        # Entwicklungsserver starten
npm run build      # Für die Produktion erstellen
npm run lint       # ESLint ausführen

Bank-Projekt API (Node.js + Express)

cd 7-bank-project/api
npm install
npm start          # API-Server starten
npm run lint       # ESLint ausführen
npm run format     # Mit Prettier formatieren

Browser-Erweiterungsprojekte

cd 5-browser-extension/solution
npm install
# Folgen Sie den browserspezifischen Anweisungen zum Laden der Erweiterung

Weltraumspiel-Projekte

cd 6-space-game/solution
npm install
# Öffne index.html im Browser oder verwende Live Server

Chat-Projekt (Python Backend)

cd 9-chat-project/solution/backend/python
pip install openai
# Setze die Umgebungsvariable GITHUB_TOKEN
python api.py

Entwicklungs-Workflow

Für Inhaltsanbieter

Forke das Repository in dein GitHub-Konto
Klon deinen Fork lokal
Erstelle einen neuen Branch für deine Änderungen
Ändere Inhalte der Lektionen oder Codebeispiele
Teste Codeänderungen in den entsprechenden Projektverzeichnissen
Reiche Pull Requests gemäß den Beitragsrichtlinien ein

Für Lernende

Forke oder klone das Repository
Navigiere nacheinander zu Lektionen-Verzeichnissen
Lies README-Dateien jeder Lektion
Absolviere Pre-Lesson-Quizze unter https://ff-quizzes.netlify.app/web/
Arbeite die Codebeispiele in den Lektionenordnern durch
Bearbeite Aufgaben und Herausforderungen
Mache Post-Lesson-Quizze

Live-Entwicklung

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

Testanweisungen

Quiz-App-Tests

cd quiz-app
npm run lint       # Überprüfen Sie auf Code-Stil-Probleme
npm run build      # Überprüfen Sie, ob der Build erfolgreich ist

Bank API-Tests

cd 7-bank-project/api
npm run lint       # Überprüfen Sie auf Probleme mit dem Code-Stil
node server.js     # Überprüfen Sie, ob der Server ohne Fehler startet

Allgemeiner Testansatz

Dies ist ein Bildungs-Repository ohne umfassende automatisierte Tests
Manuelles Testen konzentriert sich auf:
- Codebeispiele laufen fehlerfrei
- Links in der Dokumentation funktionieren korrekt
- Projekte bauen fehlerfrei
- Beispiele folgen Best Practices

Vorab-Checks vor Pull Requests

Führe npm run lint in Verzeichnissen mit package.json aus
Überprüfe ob Markdown-Links gültig sind
Teste Codebeispiele im Browser oder Node.js
Prüfe, dass Übersetzungen die richtige Struktur behalten

Code Style Richtlinien

JavaScript

Verwende moderne ES6+ Syntax
Folge den standardmäßigen ESLint-Konfigurationen der Projekte
Verwende aussagekräftige Variablen- und Funktionsnamen für Bildungszwecke
Füge erklärende Kommentare für Lernende hinzu
Formatiere mit Prettier, wenn konfiguriert

HTML/CSS

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

Python

PEP 8 Stilrichtlinien
Klare, bildungsorientierte Codebeispiele
Type Hints wo hilfreich zum Lernen

Markdown-Dokumentation

Klare Überschriftenhierarchie
Codeblöcke mit Sprachangabe
Links zu weiterführenden Ressourcen
Screenshots und Bilder in images/ Verzeichnissen
Alt-Text für Bilder für Barrierefreiheit

Dateiorganisation

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

Build und Deployment

Quiz-App Deployment (Azure Static Web Apps)

Die quiz-app ist für Azure Static Web Apps Deployment konfiguriert:

cd quiz-app
npm run build      # Erstellt den Ordner dist/
# Führt Bereitstellung über GitHub Actions Workflow bei Push auf main durch

Azure Static Web Apps Konfiguration:

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

Generierung der PDF-Dokumentation

npm install                    # Installiere docsify-to-pdf
npm run convert               # Erzeuge PDF aus Docs

Docsify Dokumentation

npm install -g docsify-cli    # Installiere Docsify global
docsify serve                 # Auf localhost:3000 bereitstellen

Projektspezifische Builds

Jedes Projektverzeichnis kann einen eigenen Build-Prozess besitzen:

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

Pull Request Richtlinien

Titel-Format

Verwende klare, beschreibende Titel, die den Änderungsbereich angeben:

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

Erforderliche Checks

Vor dem Einreichen eines PR:

Codequalität:
- Führe npm run lint in betroffenen Projektverzeichnissen aus
- Behebe alle Linting-Fehler und Warnungen
Build-Verifikation:
- Führe npm run build falls zutreffend aus
- Stelle sicher, dass keine Build-Fehler auftreten
Link-Validierung:
- Teste alle Markdown-Links
- Überprüfe Bildreferenzen
Inhaltsüberprüfung:
- Lektorat auf Rechtschreibung und Grammatik
- Stelle sicher, dass Codebeispiele korrekt und didaktisch sind
- Prüfe, dass Übersetzungen den Originalinhalt richtig wiedergeben

Beitragspflichten

D Zustimmung zur Microsoft CLA (automatische Prüfung beim ersten PR)
Folge dem Microsoft Open Source Code of Conduct
Siehe CONTRIBUTING.md für detaillierte Richtlinien
Verweise Issue-Nummern im PR-Beschreibung, falls zutreffend

Review-Prozess

PRs werden von Maintainer:innen und Community geprüft
Bildnerische Klarheit hat Priorität
Codebeispiele sollen aktuellen Best Practices folgen
Übersetzungen werden auf Genauigkeit und kulturelle Angemessenheit geprüft

Übersetzungssystem

Automatische Übersetzung

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

Manuelle Verbesserungen der Übersetzung hinzufügen

Finde Datei in translations/{language-code}/
Nimm Verbesserungen vor, Struktur soll erhalten bleiben
Sicherstellen, dass Codebeispiele funktionsfähig bleiben
Teste ggf. Quiz-Inhalte in Lokalisation

Übersetzungs-Metadaten

Übersetzte Dateien enthalten Meta-Daten-Header:

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

Debugging und Fehlerbehebung

Häufige Probleme

Quiz-App startet nicht:

Prüfe Node.js-Version (v14+ empfohlen)
Lösche node_modules und package-lock.json, führe npm install erneut aus
Prüfe Port-Konflikte (standardmäßig Vite Port 5173)

API-Server startet nicht:

Stelle sicher, dass Node.js Version >=10 ist
Prüfe, ob Port bereits belegt ist
Stelle sicher, dass alle Abhängigkeiten mit npm install installiert sind

Browser-Erweiterung lädt nicht:

Prüfe, ob manifest.json korrekt formatiert ist
Schau in die Browser-Konsole auf Fehler
Folge browserspezifischen Installationsanweisungen

Probleme mit Python Chat-Projekt:

Stelle sicher, dass OpenAI-Paket installiert ist: pip install openai
Prüfe, ob Umgebungsvariable GITHUB_TOKEN gesetzt ist
Prüfe GitHub Models-Zugriffsrechte

Docsify liefert keine Dokumentation aus:

Installiere docsify-cli global: npm install -g docsify-cli
Starte im Root-Verzeichnis des Repos
Stelle sicher, dass docs/_sidebar.md existiert

Tipps zur Entwicklungsumgebung

Verwende VS Code mit Live Server-Erweiterung für HTML-Projekte
Installiere ESLint und Prettier Erweiterungen für konsistente Formatierung
Nutze Browser DevTools zum Debuggen von JavaScript
Für Vue-Projekte: Installiere Vue DevTools Browser Erweiterung

Performance-Überlegungen

Große Anzahl übersetzter Dateien (50+ Sprachen) führt zu großen Vollklonen
Verwende flachen Klon wenn nur Inhalt bearbeitet wird: git clone --depth 1
Schließe Übersetzungen von Suchvorgängen aus, wenn du an englischen Inhalten arbeitest
Build-Prozesse können beim ersten Lauf langsam sein (npm install, Vite Build)

Sicherheitsüberlegungen

Umgebungsvariablen

API-Schlüssel dürfen niemals im Repository hinterlegt werden
Verwende .env-Dateien (schon in .gitignore enthalten)
Dokumentiere benötigte Umgebungsvariablen in Projekt-READMEs

Python-Projekte

Nutze virtuelle Umgebungen: python -m venv venv
Halte Abhängigkeiten aktuell
GitHub-Tokens sollten minimale erforderliche Berechtigungen haben

GitHub Models Zugriff

Personal Access Tokens (PAT) sind für GitHub Models erforderlich
Tokens sollten als Umgebungsvariablen gespeichert werden
Tokens oder Zugangsdaten niemals committen

Zusätzliche Hinweise

Zielgruppe

Absolute Anfänger in der Webentwicklung
Studierende und autodidaktische Lernende
Lehrkräfte, die das Curriculum im Unterricht verwenden
Inhalte sind auf Barrierefreiheit und schrittweise Kompetenzentwicklung ausgelegt

Pädagogische Philosophie

Projektbasiertes Lernen
Regelmäßige Wissensüberprüfungen (Quizze)
Praxisorientierte Coding-Übungen
Beispiele aus der realen Welt
Fokus auf Grundlagen vor Frameworks

Repository-Wartung

Aktive Community aus Lernenden und Beitragenden
Regelmäßige Updates von Abhängigkeiten und Inhalten
Probleme und Diskussionen werden von Maintainer:innen überwacht
Übersetzungsupdates automatisiert via GitHub Actions

Arbeit mit spezifischen Projekten

Für detaillierte Anweisungen zu einzelnen Projekten siehe 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 - Browser-Erweiterungsentwicklung
6-space-game/README.md - Canvas-basiertes Spiel
9-chat-project/README.md - KI-Chat-Assistent Projekt

Monorepo-Struktur

Obgleich kein klassisches Monorepo, enthält dieses Repository mehrere unabhängige Projekte:

Jede Lektion ist autark
Projekte teilen keine Abhängigkeiten
Arbeit an einzelnen Projekten ohne Einfluss auf andere
Gesamtes Repo klonen für das komplette Curriculum-Erlebnis

Haftungsausschluss:
Dieses Dokument wurde mit dem KI-Übersetzungsdienst Co-op Translator übersetzt. Obwohl wir Genauigkeit anstreben, beachten Sie bitte, dass automatisierte Übersetzungen Fehler oder Ungenauigkeiten enthalten können. Das Originaldokument in seiner Ursprungssprache gilt als maßgebliche Quelle. Für kritische Informationen wird eine professionelle menschliche Übersetzung empfohlen. Wir übernehmen keine Haftung für Missverständnisse oder Fehlinterpretationen, die durch die Verwendung dieser Übersetzung entstehen.

13 KiB Raw Blame History