14 KiB

Raw Permalink Blame History

AGENTS.md

Przegląd projektu

To repozytorium kursu edukacyjnego 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 na Klawiaturze, Rozszerzenie przeglądarki, Gra Kosmiczna, Aplikacja Bankowa, Edytor Kodów i Asystent czatu AI
Interaktywne quizy: 48 quizów po 3 pytania każdy (testy przed i po lekcji)
Wsparcie wielojęzyczne: Automatyczne tłumaczenia na ponad 50 języków dzięki GitHub Actions
Technologie: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (do projektów AI)

Architektura

Edukacyjne repozytorium z strukturą opartą na lekcjach
Każdy folder lekcji zawiera plik README, przykłady kodu i rozwiązania
Samodzielne projekty w osobnych katalogach (quiz-app, różne projekty lekcyjne)
System tłumaczeń wykorzystujący GitHub Actions (co-op-translator)
Dokumentacja serwowana przez Docsify i dostępna jako PDF

Polecenia konfiguracji

To repozytorium jest przeznaczone głównie do konsumpcji treści edukacyjnych. W celu pracy nad konkretnymi projektami:

Konfiguracja głównego repozytorium

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

Konfiguracja Quiz App (Vue 3 + Vite)

cd quiz-app
npm install
npm run dev        # Uruchom serwer deweloperski
npm run build      # Zbuduj do produkcji
npm run lint       # Uruchom ESLint

API Projekt Bankowy (Node.js + Express)

cd 7-bank-project/api
npm install
npm start          # Uruchom serwer API
npm run lint       # Uruchom ESLint
npm run format     # Sformatuj za pomocą Prettier

Projekty rozszerzeń przeglądarki

cd 5-browser-extension/solution
npm install
# Postępuj zgodnie z instrukcjami ładowania rozszerzeń specyficznymi dla przeglądarki

Projekty Gry Kosmicznej

cd 6-space-game/solution
npm install
# Otwórz index.html w przeglądarce lub użyj Live Server

Projekt czatu (backend Python)

cd 9-chat-project/solution/backend/python
pip install openai
# Ustaw zmienną środowiskową GITHUB_TOKEN
python api.py

Przepływ pracy przy tworzeniu

Dla osób wnoszących treść

Utwórz fork repozytorium na swoim koncie GitHub
Sklonuj swój fork lokalnie
Utwórz nową gałąź dla swoich zmian
Wprowadź zmiany w treści lekcji lub przykładach kodu
Przetestuj zmiany kodu w odpowiednich katalogach projektów
Prześlij pull request zgodnie z wytycznymi dotyczącymi wkładu

Dla uczących się

Zrób fork lub sklonuj repozytorium
Przechodź kolejno do folderów lekcji
Czytaj pliki README dla każdej lekcji
Wykonaj quizy przed lekcją na https://ff-quizzes.netlify.app/web/
Przerabiaj przykłady kodu w folderach lekcji
Wykonaj zadania i wyzwania
Zrób quizy po lekcji

Programowanie na żywo

Dokumentacja: Uruchom docsify serve w katalogu głównym (port 3000)
Quiz App: Uruchom npm run dev w katalogu quiz-app
Projekty: Użyj rozszerzenia VS Code Live Server dla projektów HTML
Projekty API: Uruchom npm start w odpowiednich katalogach API

Instrukcje testowania

Testowanie Quiz App

cd quiz-app
npm run lint       # Sprawdź problemy ze stylem kodu
npm run build      # Zweryfikuj, czy budowanie powiodło się

Testowanie API Bankowego

cd 7-bank-project/api
npm run lint       # Sprawdź problemy ze stylem kodu
node server.js     # Sprawdź, czy serwer uruchamia się bez błędów

Ogólne podejście do testowania

To jest repozytorium edukacyjne bez kompleksowych automatycznych testów
Testowanie manualne koncentruje się na:
- Przykłady kodu działają bez błędów
- Linki w dokumentacji działają poprawnie
- Budowy projektów przebiegają pomyślnie
- Przykłady stosują najlepsze praktyki

Sprawdzenia przed wysłaniem

Uruchom npm run lint w katalogach zawierających package.json
Sprawdź poprawność linków markdown
Przetestuj przykłady kodu w przeglądarce lub Node.js
Sprawdź, czy tłumaczenia zachowują odpowiednią strukturę

Wytyczne dotyczące stylu kodu

JavaScript

Używaj nowoczesnej składni ES6+
Stosuj standardowe konfiguracje ESLint dostarczone w projektach
Używaj znaczących nazw zmiennych i funkcji dla jasności edukacyjnej
Dodawaj komentarze wyjaśniające koncepcje dla uczących się
Formatuj kod przy pomocy Prettier tam, gdzie jest skonfigurowany

HTML/CSS

Semantyczne elementy HTML5
Zasady responsywnego projektowania
Jasne konwencje nazywania klas
Komentarze wyjaśniające techniki CSS dla uczniów

Python

Wytyczne stylu PEP 8
Jasne, edukacyjne przykłady kodu
Wskazówki typów tam, gdzie pomocne dla nauki

Dokumentacja Markdown

Jasna hierarchia nagłówków
Bloki kodu z określeniem języka
Linki do dodatkowych zasobów
Zrzuty ekranu i obrazy w katalogach images/
Teksty alternatywne dla obrazów dla dostępności

Organizacja plików

Lekcje ponumerowane kolejno (1-getting-started-lessons, 2-js-basics itd.)
Każdy projekt ma katalog solution/ i często start/ lub your-work/
Obrazy przechowywane w folderach images/ specyficznych dla lekcji
Tłumaczenia w strukturze translations/{language-code}/

Kompilacja i wdrożenie

Wdrożenie Quiz App (Azure Static Web Apps)

quiz-app jest skonfigurowany do wdrożenia jako Azure Static Web Apps:

cd quiz-app
npm run build      # Tworzy folder dist/
# Wdraża za pomocą workflow GitHub Actions przy pushu do main

Konfiguracja Azure Static Web Apps:

Lokalizacja aplikacji: /quiz-app
Lokalizacja wyjściowa: dist
Workflow: .github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml

Generowanie dokumentacji PDF

npm install                    # Zainstaluj docsify-to-pdf
npm run convert               # Wygeneruj PDF z docs

Dokumentacja Docsify

npm install -g docsify-cli    # Zainstaluj Docsify globalnie
docsify serve                 # Serwuj na localhost:3000

Budowy specyficzne dla projektu

Każdy katalog projektu może mieć własny proces budowy:

Projekty Vue: npm run build tworzy pakiety produkcyjne
Projekty statyczne: brak kroku budowy, serwuj pliki bezpośrednio

Wytyczne dotyczące pull requestów

Format tytułu

Używaj jasnych, opisowych tytułów wskazujących obszar zmian:

[Quiz-app] Dodaj nowy quiz do lekcji X
[Lesson-3] Popraw literówkę w projekcie terrarium
[Translation] Dodaj tłumaczenie na hiszpański do lekcji 5
[Docs] Aktualizuj instrukcje konfiguracji

Wymagane kontrole

Przed złożeniem PR:

Jakość kodu:
- Uruchom npm run lint w dotkniętych katalogach projektów
- Napraw wszystkie błędy i ostrzeżenia lint
Weryfikacja budowy:
- Uruchom npm run build jeśli dotyczy
- Upewnij się, że brak błędów budowania
Walidacja linków:
- Przetestuj wszystkie linki w markdown
- Zweryfikuj działanie odwołań do obrazów
Przegląd treści:
- Korekta pod względem ortografii i gramatyki
- Sprawdzenie, czy przykłady kodu są poprawne i edukacyjne
- Weryfikacja tłumaczeń pod kątem zachowania oryginalnego znaczenia

Wymagania dotyczące wkładu

Zgoda na Microsoft CLA (automatyczne sprawdzenie przy pierwszym PR)
Stosowanie Microsoft Open Source Code of Conduct
Zapoznaj się z CONTRIBUTING.md dla szczegółowych wskazówek
Odnoś się do numerów issue w opisie PR, jeśli dotyczy

Proces przeglądu

PR poddawane recenzji przez opiekunów i społeczność
Priorytet na jasność edukacyjną
Przykłady kodu powinny stosować aktualne najlepsze praktyki
Tłumaczenia weryfikowane pod kątem dokładności i odpowiedniości kulturowej

System tłumaczeń

Automatyczne tłumaczenia

Wykorzystuje 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ń

Zlokalizuj plik w translations/{language-code}/
Wprowadź poprawki, zachowując strukturę
Upewnij się, że przykłady kodu pozostają funkcjonalne
Przetestuj lokalizowane treści quizów

Metadane tłumaczenia

Przetłumaczone pliki zawierają nagłówek metadanych:

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

Debugowanie i rozwiązywanie problemów

Częste problemy

Quiz app nie uruchamia się:

Sprawdź wersję Node.js (zalecane v14+)
Usuń node_modules i package-lock.json, potem uruchom ponownie npm install
Sprawdź konflikty portów (domyślnie Vite używa portu 5173)

Serwer API nie startuje:

Sprawdź, czy wersja Node.js spełnia minimum (node >=10)
Sprawdź, czy port nie jest zajęty
Upewnij się, że wszystkie zależności zainstalowane przez npm install

Rozszerzenie przeglądarki się nie ładuje:

Sprawdź, czy manifest.json jest poprawnie sformatowany
Sprawdź błędy w konsoli przeglądarki
Postępuj zgodnie z instrukcjami instalacji dla danej przeglądarki

Problemy z projektem czatu Python:

Upewnij się, że pakiet OpenAI jest zainstalowany: pip install openai
Sprawdź, czy zmienna środowiskowa GITHUB_TOKEN jest ustawiona
Zweryfikuj 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 plik 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 jednolitego formatowania
Korzystaj z narzędzi developerskich przeglądarki do debugowania JavaScript
Dla projektów Vue zainstaluj Vue DevTools jako rozszerzenie przeglądarki

Wydajność

Duża liczba przetłumaczonych plików (ponad 50 języków) powoduje duże klony repozytorium
Używaj płytkiego klonowania, jeśli pracujesz tylko na treści: git clone --depth 1
Wyłącz tłumaczenia z wyszukiwania podczas pracy nad angielską wersją
Procesy budowania mogą być wolne przy pierwszym uruchomieniu (npm install, build Vite)

Aspekty bezpieczeństwa

Zmienne środowiskowe

Klucze API nigdy nie powinny być zapisywane w repozytorium
Używaj plików .env (już w .gitignore)
Dokumentuj wymagane zmienne środowiskowe w README projektów

Projekty Python

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) do modeli GitHub
Tokeny przechowuj jako zmienne środowiskowe
Nigdy nie commituj tokenów ani poświadczeń

Dodatkowe uwagi

Grupa docelowa

Kompletnie początkujący w tworzeniu stron internetowych
Studenci i samoucy
Nauczyciele wykorzystujący program nauczania na zajęciach
Treści zaprojektowane z uwzględnieniem dostępności i stopniowego rozwoju umiejętności

Filozofia edukacyjna

Podejście oparte na projektach
Częste sprawdzanie wiedzy (quizy)
Praktyczne ćwiczenia kodowania
Przykłady zastosowań w realnym świecie
Skupienie na fundamentach przed frameworkami

Utrzymanie repozytorium

Aktywna społeczność uczących się i współtwórców
Regularne aktualizacje zależności i treści
Monitorowanie zgłoszeń i dyskusji przez opiekunów
Aktualizacje tłumaczeń automatyzowane przez GitHub Actions

Powiązane zasoby

Moduły Microsoft Learn
Zasoby Student Hub
GitHub Copilot polecany dla uczących się
Dodatkowe kursy: Generative AI, Data Science, ML, IoT dostępne

Praca z konkretnymi projektami

Szczegółowe instrukcje dotyczące poszczególnych projektów znajdują się w plikach README:

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 - tworzenie gry 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 współdzielą zależności
Pracuj nad poszczególnymi projektami nie wpływając na inne
Sklonuj całe repozytorium, aby przejść cały kurs

Zastrzeżenie:
Niniejszy dokument został przetłumaczony przy użyciu usługi tłumaczenia AI Co-op Translator. Chociaż staramy się zapewnić dokładność, prosimy mieć na uwadze, że automatyczne tłumaczenia mogą zawierać błędy lub nieścisłości. Oryginalny dokument w jego rodzimym języku powinien być uważany za źródło autorytatywne. W przypadku informacji krytycznych zalecane jest skorzystanie z profesjonalnego tłumaczenia wykonanego przez człowieka. Nie ponosimy odpowiedzialności za jakiekolwiek nieporozumienia lub błędne interpretacje wynikające z korzystania z tego tłumaczenia.

14 KiB Raw Permalink Blame History