Skip to content

PROJECT_GUIDELINES.md

Latest commit

 

History

History
110 lines (75 loc) · 6.33 KB

PROJECT_GUIDELINES.md

File metadata and controls

110 lines (75 loc) · 6.33 KB

Руководство по оформлению проектов

Данный документ описывает требования к оформлению проектов в репозитории frontend-examples.

Содержание

Общая структура репозитория

Репозиторий организован следующим образом:

frontend-examples/
├── README.md                 # Главный README репозитория
├── PROJECT_GUIDELINES.md     # Данное руководство
└── examples/                 # Папка с проектами
    ├── project-name-1/       # Папка проекта 1
    ├── project-name-2/       # Папка проекта 2
    └── ...

Каждый проект размещается в отдельной папке внутри папки examples, которая находится в корне репозитория.

Требования к проекту

Независимость

  • Каждый проект должен быть полностью независимым и самодостаточным
  • Проект должен запускаться без необходимости установки зависимостей из других проектов репозитория
  • Все необходимые зависимости должны быть указаны в package.json проекта
  • Для удобства и быстроты развёртывания, можно явно указать значения переменных окружения в файле .env (не добавляя этот файл в .gitignore). Только если это не противоречит безопасности. На реальных проектах такое не допускается.

Минимализм

  • Проект должен демонстрировать одну конкретную фичу или набор тесно связанных фич
  • Избегайте добавления лишнего функционала, не относящегося к демонстрируемой теме
  • Код должен быть максимально простым и понятным

Актуальность

  • Используйте актуальные версии библиотек и фреймворков
  • Обновляйте проекты при выходе критических обновлений зависимостей

Документация и пояснения

  • Добавляйте поясняющие комментарии к ключевым участкам кода, особенно к нестандартным решениям
  • Для сложных концепций создавайте отдельные Markdown файлы с подробными объяснениями (например, description.md)
  • Если используется специфичный подход или обходное решение, обязательно укажите причину

Инструменты для создания проекта

  • Рекомендуется использовать Vite для быстрых и легковесных примеров
  • Используйте Next.js для примеров с серверным рендерингом или более сложной структурой
  • Избегайте использования устаревших инструментов вроде Create React App

README проекта

Каждый проект обязательно должен содержать файл README.md со следующими разделами:

Обязательные разделы

  1. Название и краткое описание

    • Что демонстрирует данный проект
    • Какую проблему решает

  2. Технологии

    • Список используемых технологий и библиотек

  3. Установка и запуск

    • Пошаговая инструкция по установке зависимостей
    • Команды для запуска проекта

  4. Описание реализации

    • Краткое объяснение ключевых моментов реализации (может быть в отдельном .md файле)
    • Ссылки на основные файлы с кодом

Опциональные разделы

  • Переменные окружения — если проект требует настройки (укажите где они задаются и как их получить)
  • Примеры использования — скриншоты или GIF-анимации работы
  • Известные ограничения — если есть
  • Полезные ссылки — документация, статьи по теме

Код и стиль

Общие рекомендации

  • Используйте TypeScript
  • Следуйте принципам чистого кода

Линтинг

  • Используйте ESLint для проверки качества кода
  • Рекомендуется использовать конфигурацию из шаблона Vite или Next.js

Чек-лист перед созданием PR

  • Проект находится в отдельной папке внутри папки examples
  • Название папки соответствует kebab-case
  • Присутствует README.md с обязательными разделами
  • Проект запускается локально без ошибок
  • Код отформатирован и проходит линтинг
  • Зависимости корректно указаны в package.json