22 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

Настройка приложения викторин (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 request, следуя руководству по внесению изменений

Для учащихся

Сделайте форк или клонируйте репозиторий
Последовательно переходите по директориям уроков
Читайте файлы README для каждого урока
Проходите викторины перед уроком на https://ff-quizzes.netlify.app/web/
Работайте с примерами кода в папках уроков
Выполняйте задания и вызовы
Проходите викторины после урока

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

Документация: Запустите docsify serve в корневой директории (порт 3000)
Приложение викторин: Запустите npm run dev в директории quiz-app
Проекты: Используйте расширение Live Server в VS Code для HTML-проектов
API-проекты: Запустите npm start в соответствующих директориях API

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

Тестирование приложения викторин

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

Тестирование 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/
Альтернативный текст для изображений для доступности

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

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

Сборка и развертывание

Развертывание приложения викторин (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 в затронутых директориях проекта
- Исправьте все ошибки и предупреждения линтинга
Проверка сборки:
- Запустите npm run build, если применимо
- Убедитесь в отсутствии ошибок сборки
Проверка ссылок:
- Проверьте все ссылки в markdown
- Убедитесь, что ссылки на изображения работают
Рецензия контента:
- Проверьте орфографию и грамматику
- Убедитесь, что примеры кода корректны и образовательны
- Проверьте, что переводы сохраняют исходный смысл

Требования к контрибьюторам

Согласие с Microsoft CLA (автоматическая проверка при первом PR)
Следование Кодексу поведения Microsoft Open Source
См. 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": "..."
}
-->

Отладка и устранение неполадок

Частые проблемы

Приложение викторин не запускается:

Проверьте версию 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

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

Установите docsify-cli глобально: npm install -g docsify-cli
Запустите из корневой директории репозитория
Убедитесь, что файл docs/_sidebar.md существует

Советы по настройке среды разработки

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

Учет производительности

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

Соображения безопасности

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

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

Проекты на Python

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

Доступ к моделям GitHub

Для моделей GitHub требуются персональные токены доступа (PAT)
Токены должны храниться как переменные окружения
Никогда не добавляйте токены или учетные данные в репозиторий

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

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

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

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

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

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

Активное сообщество учащихся и контрибьюторов
Регулярные обновления зависимостей и контента
Мониторинг задач и обсуждений мейнтейнерами
Автоматическое обновление переводов через GitHub Actions

Связанные ресурсы

Модули Microsoft Learn
Ресурсы Student Hub
GitHub Copilot рекомендуется для учащихся
Дополнительные курсы: Генеративный ИИ, 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-чат-ассистента

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

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

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

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

22 KiB Raw Blame History Unescape Escape