AGENTS.md

1# AGENTS.md
2 
3## Przegląd Projektu
4 
5To repozytorium edukacyjne służące do nauczania podstaw web developmentu dla początkujących. Program nauczania to kompleksowy 12-tygodniowy kurs opracowany przez Microsoft Cloud Advocates, obejmujący 24 praktyczne lekcje dotyczące JavaScript, CSS i HTML.
6 
7### Kluczowe Komponenty
8 
9- **Treści edukacyjne**: 24 ustrukturyzowane lekcje zorganizowane w moduły oparte na projektach
10- **Projekty praktyczne**: Terrarium, Gra Typowania, Rozszerzenie przeglądarki, Gra Kosmiczna, Aplikacja Bankowa, Edytor kodu i Asystent czatu AI
11- **Interaktywne quizy**: 48 quizów po 3 pytania (oceny przed i po lekcji)
12- **Wsparcie wielojęzyczne**: Automatyczne tłumaczenia na 50+ języków za pomocą GitHub Actions
13- **Technologie**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (dla projektów AI)
14 
15### Architektura
16 
17- Edukacyjne repozytorium o strukturze opartej na lekcjach
18- Każdy folder lekcji zawiera README, przykłady kodu i rozwiązania
19- Samodzielne projekty w osobnych katalogach (quiz-app, różne projekty lekcji)
20- System tłumaczeń wykorzystujący GitHub Actions (co-op-translator)
21- Dokumentacja serwowana przez Docsify i dostępna jako PDF
22 
23## Komendy do Ustawienia
24 
25To repozytorium jest głównie do konsumpcji treści edukacyjnych. Do pracy z konkretnymi projektami:
26 
27### Podstawowa konfiguracja repozytorium
28 
29```bash
30git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
31cd Web-Dev-For-Beginners
32```
33 
34### Konfiguracja Quiz App (Vue 3 + Vite)
35 
36```bash
37cd quiz-app
38npm install
39npm run dev        # Uruchom serwer deweloperski
40npm run build      # Buduj na produkcję
41npm run lint       # Uruchom ESLint
42```
43 
44### Bank Project API (Node.js + Express)
45 
46```bash
47cd 7-bank-project/api
48npm install
49npm start          # Uruchom serwer API
50npm run lint       # Uruchom ESLint
51npm run format     # Sformatuj za pomocą Prettier
52```
53 
54### Projekty Rozszerzenia Przeglądarki
55 
56```bash
57cd 5-browser-extension/solution
58npm install
59# Postępuj zgodnie z instrukcjami ładowania rozszerzeń specyficznymi dla przeglądarki
60```
61 
62### Projekty Gry Kosmicznej
63 
64```bash
65cd 6-space-game/solution
66npm install
67# Otwórz index.html w przeglądarce lub użyj Live Server
68```
69 
70### Projekt Czat (Backend Python)
71 
72```bash
73cd 9-chat-project/solution/backend/python
74pip install openai
75# Ustaw zmienną środowiskową GITHUB_TOKEN
76python api.py
77```
78 
79## Przebieg Rozwoju
80 
81### Dla wniesienia treści
82 
831. **Zrób fork repozytorium** na swoje konto GitHub
842. **Sklonuj swojego forka** lokalnie
853. **Utwórz nową gałąź** na swoje zmiany
864. Wprowadź zmiany w treści lekcji lub przykładach kodu
875. Testuj zmiany kodu w odpowiednich katalogach projektów
886. Prześlij pull requesty zgodnie z wytycznymi contribution
89 
90### Dla uczących się
91 
921. Zrób fork lub sklonuj repozytorium
932. Przechodź przez katalogi lekcji kolejno
943. Czytaj pliki README dla każdej lekcji
954. Wykonaj quizy przed lekcjami na https://ff-quizzes.netlify.app/web/
965. Pracuj z przykładami kodu w folderach lekcji
976. Wykonuj zadania i wyzwania
987. Przejdź quizy po lekcji
99 
100### Live Development
101 
102- **Dokumentacja**: Uruchom `docsify serve` w katalogu głównym (port 3000)
103- **Quiz App**: Uruchom `npm run dev` w katalogu quiz-app
104- **Projekty**: Użyj rozszerzenia VS Code Live Server dla projektów HTML
105- **Projekty API**: Uruchom `npm start` w odpowiednich katalogach API
106 
107## Instrukcje Testowania
108 
109### Testowanie Quiz App
110 
111```bash
112cd quiz-app
113npm run lint       # Sprawdź problemy ze stylem kodu
114npm run build      # Zweryfikuj, czy kompilacja zakończyła się sukcesem
115```
116 
117### Testowanie Bank API
118 
119```bash
120cd 7-bank-project/api
121npm run lint       # Sprawdź problemy ze stylem kodu
122node server.js     # Sprawdź, czy serwer uruchamia się bez błędów
123```
124 
125### Ogólne podejście do testowania
126 
127- To repozytorium edukacyjne bez rozbudowanych testów automatycznych
128- Testowanie ręczne skupia się na:
129  - Przykłady kodu działają bez błędów
130  - Linki w dokumentacji działają poprawnie
131  - Budowy projektów kończą się sukcesem
132  - Przykłady są zgodne z najlepszymi praktykami
133 
134### Kontrole przed wysłaniem
135 
136- Uruchom `npm run lint` w katalogach z package.json
137- Sprawdź poprawność linków markdown
138- Testuj przykłady kodu w przeglądarce lub Node.js
139- Zweryfikuj, że tłumaczenia zachowują właściwą strukturę
140 
141## Zasady Stylu Kodu
142 
143### JavaScript
144 
145- Używaj nowoczesnej składni ES6+
146- Stosuj standardowe konfiguracje ESLint podane w projektach
147- Używaj czytelnych nazw zmiennych i funkcji dla jasności edukacyjnej
148- Dodawaj komentarze objaśniające koncepcje dla uczących się
149- Formatuj przy użyciu Prettier tam, gdzie jest skonfigurowany
150 
151### HTML/CSS
152 
153- Semantyczne elementy HTML5
154- Zasady projektowania responsywnego
155- Jasna konwencja nazewnictwa klas
156- Komentarze objaśniające techniki CSS dla uczących
157 
158### Python
159 
160- Zasady stylu PEP 8
161- Jasne, edukacyjne przykłady kodu
162- Adnotacje typów tam, gdzie pomagają w nauce
163 
164### Dokumentacja w Markdown
165 
166- Jasna hierarchia nagłówków
167- Bloki kodu z określeniem języka
168- Linki do dodatkowych zasobów
169- Zrzuty ekranów i obrazy w katalogach `images/`
170- Tekst alternatywny dla obrazów dla dostępności
171 
172### Organizacja Plików
173 
174- Lekcje numerowane kolejno (1-getting-started-lessons, 2-js-basics, itd.)
175- Każdy projekt posiada katalogi `solution/` oraz często `start/` lub `your-work/`
176- Obrazy przechowywane w folderach `images/` specyficznych dla lekcji
177- Tłumaczenia w strukturze `translations/{language-code}/`
178 
179## Budowa i Wdrożenie
180 
181### Wdrożenie Quiz App (Azure Static Web Apps)
182 
183Quiz-app jest skonfigurowany do wdrożenia na Azure Static Web Apps:
184 
185```bash
186cd quiz-app
187npm run build      # Tworzy folder dist/
188# Wdraża za pomocą workflow GitHub Actions przy pushu do gałęzi main
189```
190 
191Konfiguracja Azure Static Web Apps:
192- **Lokalizacja aplikacji**: `/quiz-app`
193- **Lokalizacja outputu**: `dist`
194- **Workflow**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`
195 
196### Generowanie dokumentacji PDF
197 
198```bash
199npm install                    # Zainstaluj docsify-to-pdf
200npm run convert               # Wygeneruj plik PDF z docs
201```
202 
203### Dokumentacja Docsify
204 
205```bash
206npm install -g docsify-cli    # Zainstaluj Docsify globalnie
207docsify serve                 # Serwuj na localhost:3000
208```
209 
210### Budowy specyficzne dla projektów
211 
212Każdy katalog projektu może mieć własny proces budowy:
213- Projekty Vue: `npm run build` tworzy produkcyjne bundlery
214- Projekty statyczne: brak kroku budowania, serwuj pliki bezpośrednio
215 
216## Wytyczne dla Pull Requestów
217 
218### Format tytułu
219 
220Używaj jasnych, opisowych tytułów wskazujących obszar zmian:
221- `[Quiz-app] Dodaj nowy quiz do lekcji X`
222- `[Lesson-3] Popraw literówkę w projekcie terrarium`
223- `[Translation] Dodaj tłumaczenie na hiszpański dla lekcji 5`
224- `[Docs] Aktualizuj instrukcje konfiguracji`
225 
226### Wymagane kontrole
227 
228Przed wysłaniem PR:
229 
2301. **Jakość kodu**:
231   - Uruchom `npm run lint` w katalogach projektów
232   - Napraw wszystkie błędy i ostrzeżenia lintingu
233 
2342. **Weryfikacja builda**:
235   - Uruchom `npm run build` jeśli dotyczy
236   - Upewnij się, że brak błędów budowania
237 
2383. **Walidacja linków**:
239   - Testuj wszystkie linki markdown
240   - Sprawdź działanie odwołań do obrazów
241 
2424. **Przegląd zawartości**:
243   - Korekta ortografii i gramatyki
244   - Upewnij się, że przykłady kodu są poprawne i edukacyjne
245   - Sprawdź, czy tłumaczenia zachowują oryginalne znaczenie
246 
247### Wymagania dotyczące wkładu
248 
249- Zgoda na Microsoft CLA (automatyczna kontrola przy pierwszym PR)
250- Przestrzeganie [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/)
251- Szczegółowe wytyczne w [CONTRIBUTING.md](./CONTRIBUTING.md)
252- W referencji do PR podaj numery zgłoszeń, jeśli dotyczy
253 
254### Proces przeglądu
255 
256- PRy recenzowane przez opiekunów i społeczność
257- Priorytetem jest jasność edukacyjna
258- Przykłady kodu powinny korzystać z aktualnych najlepszych praktyk
259- Tłumaczenia sprawdzane pod kątem dokładności i odpowiedniości kulturowej
260 
261## System Tłumaczeń
262 
263### Automatyczne tłumaczenie
264 
265- Wykorzystuje GitHub Actions z workflow co-op-translator
266- Automatyczne tłumaczenie na ponad 50 języków
267- Pliki źródłowe w głównych katalogach
268- Pliki tłumaczeń w katalogach `translations/{language-code}/`
269 
270### Dodawanie ręcznych poprawek tłumaczeń
271 
2721. Znajdź plik w `translations/{language-code}/`
2732. Dokonaj poprawek zachowując strukturę
2743. Upewnij się, że przykłady kodu działają
2754. Testuj wszelkie zlokalizowane treści quizowe
276 
277### Metadane tłumaczenia
278 
279Pliki przetłumaczone zawierają nagłówek metadanych:
280```markdown
281<!--
282CO_OP_TRANSLATOR_METADATA:
283{
284  "original_hash": "...",
285  "translation_date": "...",
286  "source_file": "...",
287  "language_code": "..."
288}
289-->
290```
291 
292## Debugowanie i Rozwiązywanie Problemów
293 
294### Najczęstsze problemy
295 
296**Quiz app nie startuje**:
297- Sprawdź wersję Node.js (zalecana v14+)
298- Usuń `node_modules` i `package-lock.json`, uruchom ponownie `npm install`
299- Sprawdź konflikty portów (domyślnie Vite używa portu 5173)
300 
301**Serwer API nie uruchamia się**:
302- Sprawdź, czy wersja Node.js spełnia minimum (node >=10)
303- Sprawdź, czy port nie jest już zajęty
304- Upewnij się, że wszystkie zależności zainstalowane `npm install`
305 
306**Rozszerzenie przeglądarki się nie ładuje**:
307- Sprawdź poprawność manifest.json
308- Sprawdź konsolę przeglądarki pod kątem błędów
309- Postępuj zgodnie z instrukcjami instalacji rozszerzeń specyficznych dla przeglądarki
310 
311**Problemy z projektem czatu w Pythonie**:
312- Upewnij się, że pakiet OpenAI jest zainstalowany: `pip install openai`
313- Sprawdź, czy zmienna środowiskowa GITHUB_TOKEN jest ustawiona
314- Zweryfikuj uprawnienia dostępu do GitHub Models
315 
316**Docsify nie serwuje dokumentów**:
317- Zainstaluj docsify-cli globalnie: `npm install -g docsify-cli`
318- Uruchom z katalogu root repozytorium
319- Sprawdź, czy istnieje `docs/_sidebar.md`
320 
321### Wskazówki dotyczące środowiska programistycznego
322 
323- Używaj VS Code z rozszerzeniem Live Server dla projektów HTML
324- Zainstaluj rozszerzenia ESLint i Prettier dla spójnego formatowania
325- Korzystaj z DevTools przeglądarki do debugowania JavaScript
326- Dla projektów Vue zainstaluj rozszerzenie Vue DevTools do przeglądarki
327 
328### Względy wydajnościowe
329 
330- Duża liczba plików tłumaczeń (50+ języków) powoduje duże klony
331- Używaj płytkiego klonu jeśli pracujesz tylko nad treścią: `git clone --depth 1`
332- Wyklucz tłumaczenia z wyszukiwań podczas pracy nad angielską wersją
333- Procesy budowania mogą być wolne przy pierwszym uruchomieniu (npm install, build Vite)
334 
335## Aspekty Bezpieczeństwa
336 
337### Zmienne środowiskowe
338 
339- Klucze API nie powinny być nigdy commitowane do repozytorium
340- Używaj plików `.env` (już w `.gitignore`)
341- Udokumentuj wymagane zmienne środowiskowe w README projektów
342 
343### Projekty Python
344 
345- Używaj wirtualnych środowisk: `python -m venv venv`
346- Aktualizuj zależności na bieżąco
347- Tokenty GitHub powinny mieć minimalne wymagane uprawnienia
348 
349### Dostęp do GitHub Models
350 
351- Personal Access Tokens (PAT) wymagane do GitHub Models
352- Tokenty powinny być przechowywane jako zmienne środowiskowe
353- Nigdy nie commituj tokenów ani danych uwierzytelniających
354 
355## Dodatkowe Uwagi
356 
357### Grupa docelowa
358 
359- Całkowici początkujący w web developmencie
360- Studenci i samoucy
361- Nauczyciele korzystający z programu w klasie
362- Treść zaprojektowana z myślą o dostępności i stopniowym rozwoju umiejętności
363 
364### Filozofia edukacyjna
365 
366- Nauka oparta na projektach
367- Częste sprawdzanie wiedzy (quizy)
368- Praktyczne ćwiczenia kodowania
369- Przykłady zastosowań w realnym świecie
370- Skupienie na podstawach przed frameworkami
371 
372### Utrzymanie repozytorium
373 
374- Aktywna społeczność uczących się i współtwórców
375- Regularne aktualizacje zależności i treści
376- Monitorowane zgłoszenia i dyskusje przez opiekunów
377- Automatyczne aktualizacje tłumaczeń przez GitHub Actions
378 
379### Powiązane zasoby
380 
381- [Moduły Microsoft Learn](https://docs.microsoft.com/learn/)
382- [Zasoby Student Hub](https://docs.microsoft.com/learn/student-hub/)
383- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) rekomendowane dla uczących się
384- Dodatkowe kursy: Generative AI, Data Science, ML, IoT dostępne
385 
386### Praca z konkretnymi projektami
387 
388Dla szczegółowych instrukcji dot. poszczególnych projektów zobacz pliki README w:
389- `quiz-app/README.md` - aplikacja quizowa Vue 3
390- `7-bank-project/README.md` - aplikacja bankowa z autentykacją
391- `5-browser-extension/README.md` - rozwój rozszerzenia przeglądarki
392- `6-space-game/README.md` - rozwój gry na canvasie
393- `9-chat-project/README.md` - projekt asystenta czatu AI
394 
395### Struktura Monorepo
396 
397Chociaż to nie jest tradycyjne monorepo, repozytorium zawiera wiele niezależnych projektów:
398- Każda lekcja jest autonomiczna
399- Projekty nie dzielą zależności
400- Pracuj nad pojedynczymi projektami bez wpływu na inne
401- Sklonuj całe repo dla pełnego doświadczenia kursu
402 
403---
404 
405<!-- CO-OP TRANSLATOR DISCLAIMER START -->
406**Zastrzeżenie**:
407Niniejszy dokument został przetłumaczony przy użyciu usługi tłumaczeń AI [Co-op Translator](https://github.com/Azure/co-op-translator). Chociaż dążymy do dokładności, prosimy mieć na uwadze, że automatyczne tłumaczenia mogą zawierać błędy lub nieścisłości. Oryginalny dokument w języku źródłowym powinien być uważany za źródło autorytatywne. W przypadku istotnych informacji zaleca się profesjonalne tłumaczenie przez człowieka. Nie ponosimy odpowiedzialności za jakiekolwiek nieporozumienia lub błędne interpretacje wynikające z korzystania z tego tłumaczenia.
408<!-- CO-OP TRANSLATOR DISCLAIMER END -->