# 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 ``` ### Настройка Quiz App (Vue 3 + Vite) ```bash cd quiz-app npm install npm run dev # Запустить сервер разработки npm run build # Сборка для продакшена npm run lint # Запустить ESLint ``` ### API проекта банка (Node.js + Express) ```bash cd 7-bank-project/api npm install npm start # Запустить API сервер npm run lint # Запустить ESLint npm run format # Отформатировать с помощью Prettier ``` ### Проекты расширения браузера ```bash cd 5-browser-extension/solution npm install # Следуйте инструкциям по загрузке расширений, специфичным для браузера ``` ### Проекты космической игры ```bash cd 6-space-game/solution npm install # Откройте index.html в браузере или используйте Live Server ``` ### Проект чата (Backend на Python) ```bash cd 9-chat-project/solution/backend/python pip install openai # Установите переменную окружения GITHUB_TOKEN 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) - **Quiz App**: Запустите `npm run dev` в папке quiz-app - **Проекты**: Используйте расширение VS Code Live Server для HTML-проектов - **API-проекты**: Запустите `npm start` в соответствующих директориях API ## Инструкции по тестированию ### Тестирование Quiz App ```bash cd quiz-app npm run lint # Проверить наличие проблем со стилем кода npm run build # Проверить успешность сборки ``` ### Тестирование API банка ```bash 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: ```bash 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 документации ```bash npm install # Установить docsify-to-pdf npm run convert # Сгенерировать PDF из docs ``` ### Документация Docsify ```bash 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: 1. **Качество кода**: - Запустите `npm run lint` в затронутых папках проекта - Исправьте все ошибки и предупреждения linter 2. **Проверка сборки**: - Запустите `npm run build`, если применимо - Убедитесь в отсутствии ошибок сборки 3. **Проверка ссылок**: - Протестируйте все markdown-ссылки - Проверьте работу ссылок на изображения 4. **Проверка содержимого**: - Проверьте орфографию и грамматику - Убедитесь, что примеры кода корректны и образовательны - Проверьте точность переводов ### Требования к вкладу - Подтвердите соглашение с Microsoft CLA (автоматическая проверка при первом PR) - Следуйте [Кодексу поведения Microsoft Open Source](https://opensource.microsoft.com/codeofconduct/) - См. [CONTRIBUTING.md](./CONTRIBUTING.md) для подробных инструкций - Указывайте номера issue в описании PR при необходимости ### Процесс ревью - PR ревью проводят мейнтэйнеры и сообщество - Приоритет — образовательная ясность - Примеры кода должны соответствовать современным лучшим практикам - Переводы проверяются на точность и культурную уместность ## Система перевода ### Автоматический перевод - Используется GitHub Actions с workflow co-op-translator - Переводит автоматически на 50+ языков - Исходные файлы в основных каталогах - Переводы в каталогах `translations/{language-code}/` ### Добавление ручных улучшений перевода 1. Найдите файл в `translations/{language-code}/` 2. Внесите улучшения, сохраняя структуру 3. Убедитесь, что примеры кода работают 4. Проверьте локализованный контент викторин ### Метаданные перевода Переведённые файлы содержат заголовок с метаданными: ```markdown ``` ## Отладка и устранение неполадок ### Распространённые проблемы **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](https://docs.microsoft.com/learn/) - [Ресурсы Student Hub](https://docs.microsoft.com/learn/student-hub/) - [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=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](https://github.com/Azure/co-op-translator). Несмотря на наши усилия по обеспечению точности, пожалуйста, учитывайте, что автоматические переводы могут содержать ошибки или неточности. Оригинальный документ на исходном языке следует считать авторитетным источником. Для критически важной информации рекомендуется профессиональный перевод носителем языка. Мы не несем ответственности за любые недоразумения или неправильные толкования, возникающие в результате использования этого перевода.