Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
233 lines (167 loc) · 11.9 KB

CONTRIBUTING.md

File metadata and controls

233 lines (167 loc) · 11.9 KB

Руководство по внесению изменений

Мы рады вашему желанию внести вклад в развитие проекта! Это руководство поможет вам разобраться с процессом.

Разработка

Проект использует VS Code Tasks для удобной разработки. Все основные команды доступны через Command Palette (Ctrl+Shift+P).

Подготовка окружения

⚠️ Важно: Перед началом работы с проектом выполните следующие шаги:

  1. Установить правильную версию Node.js:

    • Нажмите Ctrl+Shift+P
    • Выберите "Tasks: Run Task"
    • Выберите "🔄 Установить Node.js из .nvmrc"
    • Или вручную: nvm use

  2. Установить зависимости:

    • Через Command Palette найдите "Tasks: Run Task"
    • Выберите "📦 Установить зависимости (npm ci)"
    • Или вручную: npm ci

  3. Настроить Git хуки (husky):

    • Это настраивает автоматические проверки перед коммитом
    • Через Command Palette выберите "🔧 Настроить Git хуки (husky)"
    • Или вручную: npm run prepare
    • ⚠️ Обязательно выполните этот шаг! Без него pre-commit хуки не будут работать.

Что делают Git хуки?

После настройки husky при каждом коммите автоматически:

  • ✅ Форматируются измененные файлы (Prettier)
  • ✅ Проверяется стиль Markdown файлов (markdownlint)
  • ✅ Проверяется орфография (cSpell)
  • ✅ Проверяется формат сообщения коммита (Conventional Commits)

Формат коммитов

Проект использует Conventional Commits. Формат сообщения коммита:

<тип>(<область>): <описание>

Типы:

  • feat - новая функциональность
  • fix - исправление ошибки
  • doc - изменения в документации
  • style - форматирование кода
  • refactor - рефакторинг
  • perf - улучшение производительности
  • test - добавление или изменение тестов
  • chore - обновление зависимостей, настройка и т.д.
  • ci - изменения в CI/CD
  • build - изменения в системе сборки
  • revert - откат изменений

Примеры:

  • feat(doc): добавить документацию по API
  • fix(core): исправить обработку ошибок
  • doc: обновить README
  • chore(ci): настроить pre-commit хуки

Запуск и разработка

Для запуска и разработки используйте команды из раздела Полезные команды ниже.

Работа с Git

Подробную информацию о pre-commit хуках смотрите в разделе Процесс проверки ниже.

Если коммит заблокирован:

  • Исправьте ошибки, указанные в выводе
  • Используйте VS Code Tasks для автоматического исправления
  • Для орфографии: проверьте слова в .cspell.json или добавьте их в словарь

Как внести свой вклад

  1. Создайте Issue

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

  2. Подготовка окружения

  3. Разработка

    • Создайте ветку для ваших изменений
    • Внесите необходимые изменения
    • Следуйте существующему стилю форматирования
    • Проверьте качество документации (см. раздел Полезные команды)
    • Запустите локальный сервер для проверки изменений (см. раздел Запуск и разработка)

  4. Создание Pull Request

    • Убедитесь, что все тесты проходят
    • Создайте Pull Request в основной репозиторий
    • Опишите внесенные изменения
    • Свяжите PR с соответствующей Issue

Требования к изменениям

  1. Качество документации

    • Соблюдайте правила оформления Markdown
    • Используйте понятный и профессиональный язык
    • Добавляйте примеры там, где это уместно

  2. Структура контента

    • Размещайте новые файлы в соответствующих разделах
    • Следуйте существующей иерархии документации
    • Обновляйте оглавление при необходимости

  3. Технические требования

    • Используйте Node.js версии, указанной в .nvmrc
    • Проверяйте работу локально перед отправкой PR
    • Следите за отсутствием ошибок линтера

Процесс проверки

Автоматические проверки

При создании Pull Request автоматически запускаются следующие проверки:

  1. Markdown Lint - проверка стиля и форматирования Markdown файлов
  2. Spellcheck - проверка орфографии
  3. Build Test - сборка документации для проверки ошибок
  4. Link Checker - проверка работоспособности всех ссылок
  5. Lighthouse - проверка производительности и доступности сайта

Все проверки должны пройти успешно перед слиянием PR.

Code Review

После прохождения автоматических проверок ваш PR будет проверен сопровождающими проекта:

  • Проверка содержания и соответствия стандартам проекта
  • Проверка форматирования и стиля
  • Проверка полноты описания изменений
  • Проверка связанных Issues

Pre-commit хуки

При каждом коммите автоматически выполняются (см. также раздел Что делают Git хуки? выше):

  • Форматирование измененных файлов (Prettier)
  • Проверка стиля Markdown файлов (markdownlint)
  • Проверка орфографии (cSpell)
  • Проверка формата сообщения коммита (Conventional Commits)

Полезные команды

VS Code Tasks (рекомендуется)

Все основные команды доступны через VS Code Tasks. Откройте Command Palette (Ctrl+Shift+P) и выберите "Tasks: Run Task":

Подготовка окружения:

  • 🔄 Установить Node.js из .nvmrc
  • 📦 Установить зависимости (npm ci)
  • 🔧 Настроить Git хуки (husky)

Разработка:

  • ▶️ Запустить Dev сервер
  • 🏗️ Собрать проект
  • 🚀 Запустить собранный проект
  • 🧹 Очистить кэш

Проверка качества:

  • 📝 Проверить Markdown
  • 🔧 Исправить Markdown
  • 📖 Проверить орфографию
  • ✨ Проверить форматирование
  • 🎨 Форматировать код
  • 🔗 Проверить ссылки
  • 🔍 Проверить уязвимости

Команды npm

Если вы предпочитаете использовать командную строку напрямую:

# Установка зависимостей
npm ci                    # установка зависимостей из package-lock.json

# Разработка
npm start                 # запуск dev сервера (обычно http://localhost:3000)
npm run build             # сборка проекта
npm run serve             # запуск собранного проекта локально
npm run clear             # очистка кэша Docusaurus

# Проверка качества
npm run lint:md           # проверка markdown файлов
npm run lint:md:fix       # автоисправление проблем в markdown
npm run spellcheck        # проверка орфографии
npm run format:check      # проверка форматирования кода
npm run format            # автоисправление форматирования кода

# Дополнительные проверки
npm run check:links       # проверка работоспособности ссылок (требует сборки)
npm run lighthouse:mobile # проверка мобильной версии (требует запущенный сервер)
npm run lighthouse:desktop # проверка десктопной версии (требует запущенный сервер)
npm run lighthouse:ci     # автоматическая проверка Lighthouse в CI

GitHub Actions

Проект использует GitHub Actions для автоматизации проверок и публикации:

  • spellcheck.yml - проверка орфографии при каждом PR
  • markdown-lint.yml - проверка стиля Markdown
  • build-test.yml - сборка и проверка документации
  • link-checker.yml - проверка работоспособности ссылок
  • lighthouse.yml - проверка производительности сайта
  • deploy.yml - автоматическая публикация на GitHub Pages

Все workflow файлы находятся в .github/workflows/. Подробнее о настройке CI/CD смотрите в документации проекта.

Вопросы и поддержка

Если у вас возникли вопросы или нужна помощь:

  1. Просмотрите существующие Issues
  2. Создайте новую Issue с вопросом (используйте шаблон "Вопрос по документации")
  3. Присоединитесь к обсуждению в Telegram
  4. Ознакомьтесь с CODE_OF_CONDUCT.md