21 KiB

Raw Permalink 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        # Стартиране на сървър за разработка
npm run build      # Създаване за продукция
npm run lint       # Стартиране на ESLint

API на банковия проект (Node.js + Express)

cd 7-bank-project/api
npm install
npm start          # Стартиране на API сървър
npm run lint       # Стартиране на ESLint
npm run format     # Форматиране с Prettier

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

cd 5-browser-extension/solution
npm install
# Следвайте указанията за зареждане на разширения специфични за браузъра

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

cd 6-space-game/solution
npm install
# Отворете index.html в браузър или използвайте Live Server

Проект за чат (Python backend)

cd 9-chat-project/solution/backend/python
pip install openai
# Задаване на променливата на средата GITHUB_TOKEN
python api.py

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

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

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

За учащите

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

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

Документация: Стартирайте docsify serve в главната директория (порт 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       # Проверка за проблеми със стила на кода
npm run build      # Проверете дали сглобяването е успешно

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

cd 7-bank-project/api
npm run lint       # Проверка за проблеми със стил на кода
node server.js     # Проверете дали сървърът стартира без грешки

Общ подход за тестване

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

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

Стартирайте 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      # Създава папка dist/
# Разгръща чрез GitHub Actions workflow при push към main

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

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

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

npm install                    # Инсталиране на docsify-to-pdf
npm run convert               # Генериране на PDF от docs

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

npm install -g docsify-cli    # Инсталирайте Docsify глобално
docsify serve                 # Сървирайте на localhost:3000

Специфични билдове за проекти

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

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

Насоки за pull request

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

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

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

Задължителни проверки

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

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

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

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

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

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

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

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

Използва GitHub Actions с workflow 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
Стартирайте от коренната директория на хранилището
Проверете дали съществува docs/_sidebar.md

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

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

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

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

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

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

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

Python проекти

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

Достъп до GitHub Models

За GitHub Models се изискват Personal Access Tokens (PAT)
Токените трябва да се съхраняват като променливи на средата
Никога не комитвайте токени или креденшъли

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

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

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

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

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

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

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

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

Microsoft Learn модули
Ресурси от Student Hub
GitHub Copilot препоръчван за учащи
Допълнителни курсове: Generative AI, Data Science, 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 Permalink Blame History Unescape Escape