# AGENTS.md ## Przegląd projektu To repozytorium edukacyjne służy do nauczania podstaw tworzenia stron internetowych dla początkujących. Program nauczania to kompleksowy 12-tygodniowy kurs opracowany przez Microsoft Cloud Advocates, zawierający 24 praktyczne lekcje obejmujące JavaScript, CSS i HTML. ### Kluczowe elementy - **Treści edukacyjne**: 24 uporządkowane lekcje zorganizowane w moduły oparte na projektach - **Projekty praktyczne**: Terrarium, Gra w pisanie, Rozszerzenie przeglądarki, Gra kosmiczna, Aplikacja bankowa, Edytor kodu i Asystent czatu AI - **Interaktywne quizy**: 48 quizów po 3 pytania każdy (oceny przed/po lekcji) - **Wsparcie dla wielu języków**: Automatyczne tłumaczenia na ponad 50 języków za pomocą GitHub Actions - **Technologie**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (dla projektów AI) ### Architektura - Repozytorium edukacyjne z strukturą opartą na lekcjach - Każdy folder lekcji zawiera README, przykłady kodu i rozwiązania - Samodzielne projekty w oddzielnych katalogach (quiz-app, różne projekty lekcji) - System tłumaczeń za pomocą GitHub Actions (co-op-translator) - Dokumentacja udostępniana przez Docsify i dostępna jako PDF ## Polecenia konfiguracji To repozytorium jest przeznaczone głównie do konsumpcji treści edukacyjnych. Aby pracować z konkretnymi projektami: ### Konfiguracja głównego repozytorium ```bash git clone https://github.com/microsoft/Web-Dev-For-Beginners.git cd Web-Dev-For-Beginners ``` ### Konfiguracja aplikacji quizowej (Vue 3 + Vite) ```bash cd quiz-app npm install npm run dev # Start development server npm run build # Build for production npm run lint # Run ESLint ``` ### API projektu bankowego (Node.js + Express) ```bash cd 7-bank-project/api npm install npm start # Start API server npm run lint # Run ESLint npm run format # Format with Prettier ``` ### Projekty rozszerzeń przeglądarki ```bash cd 5-browser-extension/solution npm install # Follow browser-specific extension loading instructions ``` ### Projekty gry kosmicznej ```bash cd 6-space-game/solution npm install # Open index.html in browser or use Live Server ``` ### Projekt czatu (backend w Pythonie) ```bash cd 9-chat-project/solution/backend/python pip install openai # Set GITHUB_TOKEN environment variable python api.py ``` ## Przepływ pracy deweloperskiej ### Dla współtwórców treści 1. **Sforkuj repozytorium** na swoje konto GitHub 2. **Sklonuj swój fork** lokalnie 3. **Utwórz nową gałąź** dla swoich zmian 4. Wprowadź zmiany w treści lekcji lub przykładach kodu 5. Przetestuj zmiany kodu w odpowiednich katalogach projektów 6. Zgłoś pull requesty zgodnie z wytycznymi dotyczącymi wkładu ### Dla uczących się 1. Sforkuj lub sklonuj repozytorium 2. Przejdź kolejno do katalogów lekcji 3. Przeczytaj pliki README dla każdej lekcji 4. Wykonaj quizy przed lekcją na https://ff-quizzes.netlify.app/web/ 5. Pracuj nad przykładami kodu w folderach lekcji 6. Wykonaj zadania i wyzwania 7. Zrób quizy po lekcji ### Rozwój na żywo - **Dokumentacja**: Uruchom `docsify serve` w katalogu głównym (port 3000) - **Aplikacja quizowa**: Uruchom `npm run dev` w katalogu quiz-app - **Projekty**: Użyj rozszerzenia Live Server w VS Code dla projektów HTML - **Projekty API**: Uruchom `npm start` w odpowiednich katalogach API ## Instrukcje testowania ### Testowanie aplikacji quizowej ```bash cd quiz-app npm run lint # Check for code style issues npm run build # Verify build succeeds ``` ### Testowanie API bankowego ```bash cd 7-bank-project/api npm run lint # Check for code style issues node server.js # Verify server starts without errors ``` ### Ogólne podejście do testowania - To repozytorium edukacyjne nie zawiera kompleksowych testów automatycznych - Testowanie ręczne koncentruje się na: - Uruchamianiu przykładów kodu bez błędów - Poprawności linków w dokumentacji - Sukcesie kompilacji projektów - Przestrzeganiu najlepszych praktyk w przykładach ### Kontrole przed zgłoszeniem - Uruchom `npm run lint` w katalogach z plikiem package.json - Zweryfikuj poprawność linków w markdown - Przetestuj przykłady kodu w przeglądarce lub Node.js - Sprawdź, czy tłumaczenia zachowują właściwą strukturę ## Wytyczne dotyczące stylu kodu ### JavaScript - Używaj nowoczesnej składni ES6+ - Przestrzegaj standardowych konfiguracji ESLint dostarczonych w projektach - Używaj znaczących nazw zmiennych i funkcji dla jasności edukacyjnej - Dodawaj komentarze wyjaśniające koncepcje dla uczących się - Formatowanie za pomocą Prettier, jeśli skonfigurowane ### HTML/CSS - Semantyczne elementy HTML5 - Zasady projektowania responsywnego - Jasne konwencje nazewnictwa klas - Komentarze wyjaśniające techniki CSS dla uczących się ### Python - Wytyczne stylu PEP 8 - Jasne, edukacyjne przykłady kodu - Podpowiedzi typów tam, gdzie są pomocne dla nauki ### Dokumentacja Markdown - Jasna hierarchia nagłówków - Bloki kodu ze specyfikacją języka - Linki do dodatkowych zasobów - Zrzuty ekranu i obrazy w katalogach `images/` - Tekst alternatywny dla obrazów dla dostępności ### Organizacja plików - Lekcje numerowane sekwencyjnie (1-getting-started-lessons, 2-js-basics, itd.) - Każdy projekt ma katalogi `solution/` i często `start/` lub `your-work/` - Obrazy przechowywane w specyficznych dla lekcji folderach `images/` - Tłumaczenia w strukturze `translations/{language-code}/` ## Budowa i wdrożenie ### Wdrożenie aplikacji quizowej (Azure Static Web Apps) Aplikacja quizowa jest skonfigurowana do wdrożenia w Azure Static Web Apps: ```bash cd quiz-app npm run build # Creates dist/ folder # Deploys via GitHub Actions workflow on push to main ``` Konfiguracja Azure Static Web Apps: - **Lokalizacja aplikacji**: `/quiz-app` - **Lokalizacja wynikowa**: `dist` - **Workflow**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml` ### Generowanie dokumentacji PDF ```bash npm install # Install docsify-to-pdf npm run convert # Generate PDF from docs ``` ### Dokumentacja Docsify ```bash npm install -g docsify-cli # Install Docsify globally docsify serve # Serve on localhost:3000 ``` ### Budowa specyficzna dla projektów Każdy katalog projektu może mieć własny proces budowy: - Projekty Vue: `npm run build` tworzy pakiety produkcyjne - Projekty statyczne: Brak kroku budowy, pliki serwowane bezpośrednio ## Wytyczne dotyczące pull requestów ### Format tytułu Używaj jasnych, opisowych tytułów wskazujących obszar zmiany: - `[Quiz-app] Dodaj nowy quiz dla lekcji X` - `[Lesson-3] Popraw literówkę w projekcie terrarium` - `[Translation] Dodaj tłumaczenie na hiszpański dla lekcji 5` - `[Docs] Zaktualizuj instrukcje konfiguracji` ### Wymagane kontrole Przed zgłoszeniem PR: 1. **Jakość kodu**: - Uruchom `npm run lint` w dotkniętych katalogach projektów - Napraw wszystkie błędy i ostrzeżenia lintingu 2. **Weryfikacja budowy**: - Uruchom `npm run build`, jeśli dotyczy - Upewnij się, że nie ma błędów budowy 3. **Walidacja linków**: - Przetestuj wszystkie linki w markdown - Zweryfikuj poprawność odniesień do obrazów 4. **Przegląd treści**: - Sprawdź pisownię i gramatykę - Upewnij się, że przykłady kodu są poprawne i edukacyjne - Zweryfikuj, czy tłumaczenia zachowują oryginalne znaczenie ### Wymagania dotyczące wkładu - Zgoda na Microsoft CLA (automatyczna kontrola przy pierwszym PR) - Przestrzeganie [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/) - Zobacz [CONTRIBUTING.md](./CONTRIBUTING.md) dla szczegółowych wytycznych - Odnoś numery problemów w opisie PR, jeśli dotyczy ### Proces przeglądu - PR-y przeglądane przez opiekunów i społeczność - Priorytetem jest jasność edukacyjna - Przykłady kodu powinny przestrzegać aktualnych najlepszych praktyk - Tłumaczenia przeglądane pod kątem dokładności i odpowiedniości kulturowej ## System tłumaczeń ### Automatyczne tłumaczenie - Używa GitHub Actions z workflow co-op-translator - Automatycznie tłumaczy na ponad 50 języków - Pliki źródłowe w głównych katalogach - Przetłumaczone pliki w katalogach `translations/{language-code}/` ### Dodawanie ręcznych ulepszeń tłumaczeń 1. Znajdź plik w `translations/{language-code}/` 2. Wprowadź ulepszenia, zachowując strukturę 3. Upewnij się, że przykłady kodu pozostają funkcjonalne 4. Przetestuj wszelkie zlokalizowane treści quizowe ### Metadane tłumaczeń Przetłumaczone pliki zawierają nagłówek metadanych: ```markdown ``` ## Debugowanie i rozwiązywanie problemów ### Typowe problemy **Aplikacja quizowa nie uruchamia się**: - Sprawdź wersję Node.js (zalecana v14+) - Usuń `node_modules` i `package-lock.json`, uruchom ponownie `npm install` - Sprawdź konflikty portów (domyślnie: Vite używa portu 5173) **Serwer API nie uruchamia się**: - Zweryfikuj, czy wersja Node.js spełnia minimalne wymagania (node >=10) - Sprawdź, czy port jest już używany - Upewnij się, że wszystkie zależności są zainstalowane za pomocą `npm install` **Rozszerzenie przeglądarki nie ładuje się**: - Zweryfikuj, czy manifest.json jest poprawnie sformatowany - Sprawdź konsolę przeglądarki pod kątem błędów - Postępuj zgodnie z instrukcjami instalacji rozszerzenia specyficznymi dla przeglądarki **Problemy z projektem czatu w Pythonie**: - Upewnij się, że pakiet OpenAI jest zainstalowany: `pip install openai` - Zweryfikuj, czy zmienna środowiskowa GITHUB_TOKEN jest ustawiona - Sprawdź uprawnienia dostępu do GitHub Models **Docsify nie serwuje dokumentacji**: - Zainstaluj docsify-cli globalnie: `npm install -g docsify-cli` - Uruchom z katalogu głównego repozytorium - Sprawdź, czy istnieje `docs/_sidebar.md` ### Wskazówki dotyczące środowiska deweloperskiego - Używaj VS Code z rozszerzeniem Live Server dla projektów HTML - Zainstaluj rozszerzenia ESLint i Prettier dla spójnego formatowania - Używaj narzędzi deweloperskich przeglądarki do debugowania JavaScript - Dla projektów Vue zainstaluj rozszerzenie Vue DevTools dla przeglądarki ### Rozważania dotyczące wydajności - Duża liczba przetłumaczonych plików (ponad 50 języków) oznacza, że pełne klony są duże - Użyj płytkiego klonowania, jeśli pracujesz tylko nad treścią: `git clone --depth 1` - Wyklucz tłumaczenia z wyszukiwań podczas pracy nad treścią w języku angielskim - Procesy budowy mogą być wolne przy pierwszym uruchomieniu (npm install, Vite build) ## Rozważania dotyczące bezpieczeństwa ### Zmienne środowiskowe - Klucze API nigdy nie powinny być dodawane do repozytorium - Używaj plików `.env` (już w `.gitignore`) - Dokumentuj wymagane zmienne środowiskowe w README projektów ### Projekty w Pythonie - Używaj wirtualnych środowisk: `python -m venv venv` - Aktualizuj zależności - Tokeny GitHub powinny mieć minimalne wymagane uprawnienia ### Dostęp do GitHub Models - Wymagane są Personal Access Tokens (PAT) dla GitHub Models - Tokeny powinny być przechowywane jako zmienne środowiskowe - Nigdy nie dodawaj tokenów ani danych uwierzytelniających ## Dodatkowe uwagi ### Docelowa grupa odbiorców - Całkowici początkujący w tworzeniu stron internetowych - Studenci i osoby uczące się samodzielnie - Nauczyciele korzystający z programu nauczania w klasach - Treści zaprojektowane z myślą o dostępności i stopniowym budowaniu umiejętności ### Filozofia edukacyjna - Podejście oparte na projektach - Częste sprawdzanie wiedzy (quizy) - Praktyczne ćwiczenia kodowania - Przykłady zastosowań w rzeczywistych sytuacjach - Skupienie na podstawach przed przejściem do frameworków ### Utrzymanie repozytorium - Aktywna społeczność uczących się i współtwórców - Regularne aktualizacje zależności i treści - Problemy i dyskusje monitorowane przez opiekunów - Aktualizacje tłumaczeń automatyzowane za pomocą GitHub Actions ### Powiązane zasoby - [Moduły Microsoft Learn](https://docs.microsoft.com/learn/) - [Zasoby Student Hub](https://docs.microsoft.com/learn/student-hub/) - [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) polecany dla uczących się - Dodatkowe kursy: Generative AI, Data Science, ML, IoT dostępne w programie nauczania ### Praca z konkretnymi projektami Szczegółowe instrukcje dotyczące poszczególnych projektów znajdziesz w plikach README w: - `quiz-app/README.md` - aplikacja quizowa Vue 3 - `7-bank-project/README.md` - aplikacja bankowa z uwierzytelnianiem - `5-browser-extension/README.md` - rozwój rozszerzeń przeglądarki - `6-space-game/README.md` - rozwój gry opartej na Canvas - `9-chat-project/README.md` - projekt asystenta czatu AI ### Struktura monorepo Chociaż nie jest to tradycyjne monorepo, to repozytorium zawiera wiele niezależnych projektów: - Każda lekcja jest samodzielna - Projekty nie dzielą zależności - Pracuj nad poszczególnymi projektami bez wpływu na inne - Sklonuj całe repozytorium, aby uzyskać pełne doświadczenie programu nauczania --- **Zastrzeżenie**: Ten dokument został przetłumaczony za pomocą usługi tłumaczenia AI [Co-op Translator](https://github.com/Azure/co-op-translator). Chociaż staramy się zapewnić dokładność, prosimy pamiętać, że automatyczne tłumaczenia mogą zawierać błędy lub nieścisłości. Oryginalny dokument w jego języku źródłowym powinien być uznawany za autorytatywne źródło. W przypadku informacji krytycznych zaleca się skorzystanie z profesjonalnego tłumaczenia przez człowieka. Nie ponosimy odpowiedzialności za jakiekolwiek nieporozumienia lub błędne interpretacje wynikające z użycia tego tłumaczenia.