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        # Запустить сервер разработки
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

Проект чата (Backend на Python)

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
Проекты: Используйте расширение VS Code Live Server для HTML-проектов
API-проекты: Запустите npm start в соответствующих директориях API

Инструкции по тестированию

Тестирование Quiz App

cd quiz-app
npm run lint       # Проверить наличие проблем со стилем кода
npm run build      # Проверить успешность сборки

Тестирование 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/
# Выполняет деплой через workflow GitHub Actions при пуше в 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 request

Формат заголовка

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

[Quiz-app] Добавить новую викторину для урока X
[Lesson-3] Исправить опечатку в проекте террариума
[Translation] Добавить испанский перевод для урока 5
[Docs] Обновить инструкции по настройке

Требуемые проверки

Перед отправкой PR:

Качество кода:
- Запустите npm run lint в затронутых папках проекта
- Исправьте все ошибки и предупреждения linter
Проверка сборки:
- Запустите npm run build, если применимо
- Убедитесь в отсутствии ошибок сборки
Проверка ссылок:
- Протестируйте все markdown-ссылки
- Проверьте работу ссылок на изображения
Проверка содержимого:
- Проверьте орфографию и грамматику
- Убедитесь, что примеры кода корректны и образовательны
- Проверьте точность переводов

Требования к вкладу

Подтвердите соглашение с Microsoft CLA (автоматическая проверка при первом PR)
Следуйте Кодексу поведения Microsoft Open Source
См. CONTRIBUTING.md для подробных инструкций
Указывайте номера issue в описании 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 не ниже 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)

Вопросы безопасности

Переменные окружения

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

Python проекты

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

Доступ к GitHub Models

Для работы с GitHub Models нужны Personal Access Tokens (PAT)
Токены должны храниться как переменные окружения
Никогда не коммитьте токены или креденшалы

Дополнительные заметки

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

Полные новички в веб-разработке
Студенты и самоучки
Преподаватели, использующие программу в классе
Контент разработан для доступности и поэтапного освоения навыков

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

Проектно-ориентированный подход к обучению
Частые проверки знаний (викторины)
Практические упражнения по коду
Примеры из реальных сценариев
Акцент на фундаментальные знания перед фреймворками

Поддержка репозитория

Активное сообщество учащихся и контрибьюторов
Регулярные обновления зависимостей и контента
Контроль за issue и обсуждениями мейнтэйнерами
Обновления переводов автоматизированы через 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 чат-ассистента

Структура монорепозитория

Хотя это не традиционный монорепозиторий, он содержит несколько независимых проектов:

Каждый урок автономен
Проекты не разделяют зависимости
Можно работать с отдельными проектами, не затрагивая другие
Клонируйте весь репозиторий для полного освоения учебной программы

Отказ от ответственности:
Этот документ был переведен с помощью сервиса автоматического перевода Co-op Translator. Несмотря на наши усилия по обеспечению точности, пожалуйста, учитывайте, что автоматические переводы могут содержать ошибки или неточности. Оригинальный документ на исходном языке следует считать авторитетным источником. Для критически важной информации рекомендуется профессиональный перевод носителем языка. Мы не несем ответственности за любые недоразумения или неправильные толкования, возникающие в результате использования этого перевода.

21 KiB Raw Blame History Unescape Escape