21 KiB

Raw Permalink Blame History Unescape Escape

AGENTS.md

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

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

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

Образователно съдържание: 24 структурирани урока, организирани в модули, базирани на проекти
Практически проекти: Terrarium, Typing Game, Browser Extension, Space Game, Banking App, Code Editor и AI Chat Assistant
Интерактивни тестове: 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 на Bank проект (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
# Следвайте указанията за зареждане на разширения специфични за браузъра

Проекти за Space Game

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

Chat проект (Python backend)

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

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

За допринасящи с съдържание

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

За учащи се

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

Живо разработване

Документация: Стартирайте docsify serve в корена (порт 3000)
Quiz App: Стартирайте npm run dev в директорията quiz-app
Проекти: Използвайте разширението VS Code Live Server за 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/
Алтернативен текст за изображенията за достъпност

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

Уроците са номерирани последователно (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
Workflow: .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 заявки

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

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

[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 с 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

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

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

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

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

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

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

Поддръжка на репозиториума

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

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

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

Работа със специфични проекти

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

quiz-app/README.md - Vue 3 quiz приложение
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