21 KiB

Raw Blame History Unescape Escape

AGENTS.md

Преглед на проекта

Това е хранилище за образователна учебна програма, предназначена за обучение на начинаещи в основите на уеб разработката. Учебната програма представлява цялостен 12-седмичен курс, разработен от Microsoft Cloud Advocates, включващ 24 практически урока, обхващащи JavaScript, CSS и HTML.

Основни компоненти

Образователно съдържание: 24 структурирани урока, организирани в модули, базирани на проекти
Практически проекти: Терариум, Игра за писане, Разширение за браузър, Космическа игра, Банково приложение, Редактор на код и AI чат асистент
Интерактивни тестове: 48 теста с по 3 въпроса (оценки преди/след урока)
Поддръжка на много езици: Автоматични преводи на над 50 езика чрез GitHub Actions
Технологии: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (за AI проекти)

Архитектура

Образователно хранилище със структура, базирана на уроци
Всяка папка с урок съдържа README, примери за код и решения
Самостоятелни проекти в отделни директории (quiz-app, различни проекти за уроци)
Система за превод чрез GitHub Actions (co-op-translator)
Документация, предоставена чрез Docsify и налична като PDF

Команди за настройка

Това хранилище е основно за консумация на образователно съдържание. За работа с конкретни проекти:

Основна настройка на хранилището

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

Настройка на Quiz App (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

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

Проекти за разширения за браузър

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

Проекти за космическа игра

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

Чат проект (Python Backend)

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

Работен процес за разработка

За сътрудници на съдържание

Форкнете хранилището към вашия GitHub акаунт
Клонирайте вашия форк локално
Създайте нов клон за вашите промени
Направете промени в съдържанието на уроците или примерите за код
Тествайте промените в кода в съответните директории на проектите
Изпратете pull requests, следвайки указанията за принос

За учащи

Форкнете или клонирайте хранилището
Навигирайте до директориите на уроците последователно
Прочетете README файловете за всеки урок
Завършете тестовете преди урока на https://ff-quizzes.netlify.app/web/
Работете върху примерите за код в папките на уроците
Завършете задачите и предизвикателствата
Направете тестовете след урока

Жива разработка

Документация: Стартирайте docsify serve в root (порт 3000)
Quiz App: Стартирайте npm run dev в директорията quiz-app
Проекти: Използвайте разширението Live Server на VS Code за HTML проекти
API проекти: Стартирайте npm start в съответните API директории

Инструкции за тестване

Тестване на Quiz App

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

Тестване на Bank API

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

Общ подход към тестване

Това е образователно хранилище без изчерпателни автоматизирани тестове
Ръчното тестване се фокусира върху:
- Примерите за код се изпълняват без грешки
- Линковете в документацията работят правилно
- Проектите се изграждат успешно
- Примерите следват най-добрите практики

Проверки преди подаване

Стартирайте npm run lint в директории с package.json
Уверете се, че линковете в markdown са валидни
Тествайте примерите за код в браузър или Node.js
Проверете дали преводите запазват правилната структура

Насоки за стил на код

JavaScript

Използвайте модерен ES6+ синтаксис
Следвайте стандартните конфигурации на ESLint, предоставени в проектите
Използвайте смислени имена на променливи и функции за образователна яснота
Добавяйте коментари, обясняващи концепции за учащите
Форматирайте с Prettier, където е конфигуриран

HTML/CSS

Семантични HTML5 елементи
Принципи на отзивчив дизайн
Ясни конвенции за именуване на класове
Коментари, обясняващи CSS техники за учащите

Python

Насоки за стил PEP 8
Ясни, образователни примери за код
Типови подсказки, където са полезни за обучение

Markdown документация

Ясна йерархия на заглавията
Блокове с код със спецификация на езика
Линкове към допълнителни ресурси
Скрийншоти и изображения в директории images/
Alt текст за изображения за достъпност

Организация на файловете

Уроците са номерирани последователно (1-getting-started-lessons, 2-js-basics и т.н.)
Всеки проект има solution/ и често start/ или your-work/ директории
Изображенията се съхраняват в специфични за урока папки images/
Преводите са в структура translations/{language-code}/

Изграждане и разгръщане

Разгръщане на Quiz App (Azure Static Web Apps)

Quiz-app е конфигуриран за разгръщане в Azure Static Web Apps:

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

Конфигурация на Azure Static Web Apps:

Местоположение на приложението: /quiz-app
Местоположение на изхода: dist
Работен процес: .github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml

Генериране на PDF документация

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

Документация Docsify

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

Изграждане на специфични за проектите

Всяка директория на проект може да има свой собствен процес на изграждане:

Vue проекти: npm run build създава производствени пакети
Статични проекти: Няма стъпка за изграждане, файловете се обслужват директно

Насоки за Pull Request

Формат на заглавието

Използвайте ясни, описателни заглавия, указващи областта на промяната:

[Quiz-app] Добавяне на нов тест за урок X
[Lesson-3] Поправка на правописна грешка в проекта за терариум
[Translation] Добавяне на испански превод за урок 5
[Docs] Актуализиране на инструкции за настройка

Необходими проверки

Преди подаване на PR:

Качество на кода:
- Стартирайте npm run lint в засегнатите директории на проекта
- Поправете всички грешки и предупреждения за lint
Проверка на изграждането:
- Стартирайте npm run build, ако е приложимо
- Уверете се, че няма грешки при изграждането
Валидиране на линкове:
- Тествайте всички линкове в markdown
- Уверете се, че препратките към изображения работят
Преглед на съдържанието:
- Проверете за правописни и граматически грешки
- Уверете се, че примерите за код са правилни и образователни
- Проверете дали преводите запазват оригиналното значение

Изисквания за принос

Съгласие с Microsoft CLA (автоматична проверка при първия PR)
Следване на Microsoft Open Source Code of Conduct
Вижте CONTRIBUTING.md за подробни указания
Посочете номера на проблема в описанието на PR, ако е приложимо

Процес на преглед

PR се преглеждат от поддържащите и общността
Образователната яснота е приоритет
Примерите за код трябва да следват текущите най-добри практики
Преводите се преглеждат за точност и културна уместност

Система за превод

Автоматичен превод

Използва GitHub Actions с работен процес co-op-translator
Превежда автоматично на над 50 езика
Изходните файлове са в основните директории
Преведените файлове са в директории translations/{language-code}/

Добавяне на ръчни подобрения на превода

Намерете файла в translations/{language-code}/
Направете подобрения, като запазите структурата
Уверете се, че примерите за код остават функционални
Тествайте всяко локализирано съдържание на тестове

Метаданни за превод

Преведените файлове включват заглавка с метаданни:

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

Отстраняване на грешки и проблеми

Чести проблеми

Quiz app не стартира:

Проверете версията на Node.js (препоръчва се v14+)
Изтрийте node_modules и package-lock.json, стартирайте npm install отново
Проверете за конфликти на портове (по подразбиране: Vite използва порт 5173)

API сървърът не стартира:

Уверете се, че версията на Node.js отговаря на минималните изисквания (node >=10)
Проверете дали портът вече се използва
Уверете се, че всички зависимости са инсталирани с npm install

Разширението за браузър не се зарежда:

Проверете дали manifest.json е правилно форматиран
Проверете конзолата на браузъра за грешки
Следвайте специфичните за браузъра инструкции за инсталиране на разширения

Проблеми с Python чат проекта:

Уверете се, че пакетът OpenAI е инсталиран: pip install openai
Проверете дали променливата на средата GITHUB_TOKEN е зададена
Проверете разрешенията за достъп до GitHub Models

Docsify не обслужва документацията:

Инсталирайте docsify-cli глобално: npm install -g docsify-cli
Стартирайте от root директорията на хранилището
Проверете дали docs/_sidebar.md съществува

Съвети за работна среда

Използвайте VS Code с разширението Live Server за HTML проекти
Инсталирайте разширенията ESLint и Prettier за последователно форматиране
Използвайте DevTools на браузъра за дебъгване на JavaScript
За Vue проекти инсталирайте разширението Vue DevTools за браузъра

Съображения за производителност

Голям брой преведени файлове (над 50 езика) означава, че пълните клони са големи
Използвайте плитко клониране, ако работите само върху съдържание: git clone --depth 1
Изключете преводите от търсенията, когато работите върху съдържание на английски
Процесите на изграждане може да са бавни при първото стартиране (npm install, Vite build)

Съображения за сигурност

Променливи на средата

API ключовете никога не трябва да се комитират в хранилището
Използвайте .env файлове (вече в .gitignore)
Документирайте необходимите променливи на средата в README файловете на проектите

Python проекти

Използвайте виртуални среди: python -m venv venv
Поддържайте зависимостите актуални
GitHub токените трябва да имат минимално необходимите разрешения

Достъп до GitHub Models

Лични токени за достъп (PAT) са необходими за GitHub Models
Токените трябва да се съхраняват като променливи на средата
Никога не комитвайте токени или идентификационни данни

Допълнителни бележки

Целева аудитория

Напълно начинаещи в уеб разработката
Студенти и самостоятелни учащи
Учители, използващи учебната програма в класове
Съдържанието е проектирано за достъпност и постепенно изграждане на умения

Образователна философия

Подход, базиран на проекти
Чести проверки на знанията (тестове)
Практически упражнения за кодиране
Примери за реално приложение
Фокус върху основите преди фреймуърковете

Поддръжка на хранилището

Активна общност от учащи и сътрудници
Редовни актуализации на зависимостите и съдържанието
Проблемите и дискусиите се наблюдават от поддържащите
Актуализациите на преводите се автоматизират чрез GitHub Actions

Свързани ресурси

Модули на Microsoft Learn
Ресурси на Student Hub
GitHub Copilot препоръчва се за учащи
Допълнителни курсове: Генеративен AI, Наука за данни, ML, IoT учебни програми

Работа с конкретни проекти

За подробни инструкции относно отделните проекти, вижте README файловете в:

quiz-app/README.md - Vue 3 приложение за тестове
7-bank-project/README.md - Банково приложение с автентикация
5-browser-extension/README.md - Разработка на разширение за браузър
6-space-game/README.md - Разработка на игра, базирана на Canvas
9-chat-project/README.md - Проект за AI чат асистент

Структура на монорепото

Въпреки че не е традиционно монорепо, това хранилище съдържа множество независими проекти:

Всеки урок е самостоятелен
Проектите не споделят зависимости
Работете върху отделни проекти, без да засягате други
Клонирайте цялото хранилище за пълно учебно преживяване

Отказ от отговорност:
Този документ е преведен с помощта на AI услуга за превод Co-op Translator. Въпреки че се стремим към точност, моля, имайте предвид, че автоматизираните преводи може да съдържат грешки или неточности. Оригиналният документ на неговия роден език трябва да се счита за авторитетен източник. За критична информация се препоръчва професионален човешки превод. Ние не носим отговорност за недоразумения или погрешни интерпретации, произтичащи от използването на този превод.

21 KiB Raw Blame History Unescape Escape