# 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 ## Команды для настройки Этот репозиторий предназначен в первую очередь для потребления образовательного контента. Для работы с конкретными проектами: ### Настройка основного репозитория ```bash git clone https://github.com/microsoft/Web-Dev-For-Beginners.git cd Web-Dev-For-Beginners ``` ### Настройка приложения викторин (Vue 3 + Vite) ```bash 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) ```bash cd 7-bank-project/api npm install npm start # Start API server npm run lint # Run ESLint npm run format # Format with Prettier ``` ### Проекты расширений для браузера ```bash cd 5-browser-extension/solution npm install # Follow browser-specific extension loading instructions ``` ### Проекты космической игры ```bash cd 6-space-game/solution npm install # Open index.html in browser or use Live Server ``` ### Проект чата (Python Backend) ```bash cd 9-chat-project/solution/backend/python pip install openai # Set GITHUB_TOKEN environment variable python api.py ``` ## Рабочий процесс разработки ### Для контрибьюторов контента 1. **Сделайте форк репозитория** в свой аккаунт GitHub 2. **Клонируйте свой форк** локально 3. **Создайте новую ветку** для ваших изменений 4. Внесите изменения в контент уроков или примеры кода 5. Протестируйте изменения кода в соответствующих директориях проектов 6. Отправьте pull request, следуя руководству по внесению изменений ### Для учащихся 1. Сделайте форк или клонируйте репозиторий 2. Последовательно переходите по директориям уроков 3. Читайте файлы README для каждого урока 4. Проходите викторины перед уроком на https://ff-quizzes.netlify.app/web/ 5. Работайте с примерами кода в папках уроков 6. Выполняйте задания и вызовы 7. Проходите викторины после урока ### Живая разработка - **Документация**: Запустите `docsify serve` в корневой директории (порт 3000) - **Приложение викторин**: Запустите `npm run dev` в директории quiz-app - **Проекты**: Используйте расширение Live Server в VS Code для HTML-проектов - **API-проекты**: Запустите `npm start` в соответствующих директориях API ## Инструкции по тестированию ### Тестирование приложения викторин ```bash cd quiz-app npm run lint # Check for code style issues npm run build # Verify build succeeds ``` ### Тестирование API для банка ```bash 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: ```bash 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 ```bash npm install # Install docsify-to-pdf npm run convert # Generate PDF from docs ``` ### Документация Docsify ```bash 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: 1. **Качество кода**: - Запустите `npm run lint` в затронутых директориях проекта - Исправьте все ошибки и предупреждения линтинга 2. **Проверка сборки**: - Запустите `npm run build`, если применимо - Убедитесь в отсутствии ошибок сборки 3. **Проверка ссылок**: - Проверьте все ссылки в markdown - Убедитесь, что ссылки на изображения работают 4. **Рецензия контента**: - Проверьте орфографию и грамматику - Убедитесь, что примеры кода корректны и образовательны - Проверьте, что переводы сохраняют исходный смысл ### Требования к контрибьюторам - Согласие с Microsoft CLA (автоматическая проверка при первом PR) - Следование [Кодексу поведения Microsoft Open Source](https://opensource.microsoft.com/codeofconduct/) - См. [CONTRIBUTING.md](./CONTRIBUTING.md) для подробных инструкций - Укажите номера задач в описании PR, если применимо ### Процесс рецензии - PR рецензируются мейнтейнерами и сообществом - Приоритет отдается образовательной ясности - Примеры кода должны соответствовать современным лучшим практикам - Переводы проверяются на точность и культурную уместность ## Система перевода ### Автоматический перевод - Использует GitHub Actions с рабочим процессом co-op-translator - Автоматически переводит на более чем 50 языков - Исходные файлы находятся в основных директориях - Переведенные файлы находятся в директориях `translations/{language-code}/` ### Добавление улучшений в переводы вручную 1. Найдите файл в `translations/{language-code}/` 2. Внесите улучшения, сохраняя структуру 3. Убедитесь, что примеры кода остаются функциональными 4. Протестируйте локализованный контент викторин ### Метаданные перевода Переведенные файлы включают заголовок метаданных: ```markdown ``` ## Отладка и устранение неполадок ### Частые проблемы **Приложение викторин не запускается**: - Проверьте версию 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](https://docs.microsoft.com/learn/) - [Ресурсы Student Hub](https://docs.microsoft.com/learn/student-hub/) - [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=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](https://github.com/Azure/co-op-translator). Несмотря на наши усилия обеспечить точность, автоматические переводы могут содержать ошибки или неточности. Оригинальный документ на его исходном языке следует считать авторитетным источником. Для получения критически важной информации рекомендуется профессиональный перевод человеком. Мы не несем ответственности за любые недоразумения или неправильные толкования, возникшие в результате использования данного перевода.