↓ Перейти к основному содержимому
Блог maxqwars

Перевод руководства для контрибюторов Metaform

·1285 слов·7 минут·
Оглавление

Благодарим за проявленный интерес к проекту
#

Спасибо за желание сделать Metaform лучше! В этом документе описаны правила и процесс внесения изменений в проект. Этот файл поможет вам разобраться в процессе внесения вклада в проект, от первых шагов до pull request.

Организация ветвей
#

⚠️ Важно: до выпуска версии 2.0 ветка main не отражает текущую опубликованную в npm версию. Это временное исключение связано с подготовкой релиза 2.0. После выпуска 2.0 данное уведомление будет удалено, а main и develop будут работать по правилам, описанным ниже.

⚠️ Все изменения вносите в ветку develop. Эта ветка предназначена для текущей разработки и может содержать как новые возможности, так и изменения, которые ещё не вошли в релиз.

⚠️ Изменения из develop попадают в main только при подготовке нового релиза. Поэтому main не должна содержать изменений, нарушающих обратную совместимость с текущей версией latest.

⚠️ Финальная версия публикуется автоматически из ветки main — за это отвечает maintainer. Изменения в CHANGELOG.md и настройки инструментов сборки вносит только maintainer, за исключением заранее оговорённых случаев.

Кратко

  • Эти правила полноценно вступают в силу после полноценного релиза v2.0.0
  • develop — вся текущая разработка и новые изменения.
  • main — последняя стабильная версия, опубликованная в npm.
  • main должна оставаться обратно совместимой с текущим latest.
  • Финальная версия публикуется автоматически из ветки main, за это отвечает maintainer, изменения CHANGELOG.md настройки инструментов сборки меняет только maintainer, за исключением заранее оговоренных случаев.
  • Breaking changes требуют изменения версии перед попаданием в main.

Семантическое версирование
#

Metaform следует принципам семантического управления версиями. Мы выпускаем исправляющие версии (patch) для устранения ошибок, минорные (minor) — для добавления новых возможностей, и мажорные (major) — для изменений, нарушающих обратную совместимость.

Получение кода Metaform и настройка окружения
#

Требования к платформе
#

  • Nodejs (версии 24.0.0^ или выше)
  • Пакетный менеджер: pnpm (11.20.0 или выше)

Клонирование проекта и установка зависимостей
#


# Получение репозитория
git clone https://github.com/maxqwars/metaform.git
cd metaform/

# Обновление данных
git fetch origin

# Переход на ветку develop
git checkout develop

# Установка зависимостей
pnpm install

Список скриптов
#

  • pnpm dev — запуск сборщика в режиме отслеживания изменений (watch mode).
  • pnpm test — запуск модульных тестов с помощью Vitest.
  • pnpm test:coverage — проверка покрытия кода тестами.
  • pnpm typecheck — проверка типов TypeScript.
  • pnpm lint — проверка кода линтером.
  • pnpm format — автоматическое форматирование кода через Prettier.

💡 Архитектура и структура кода: Перед тем как писать код или добавлять новые эндпоинты, обязательно ознакомьтесь с Архитектурным руководством (ARCHITECTURE.md). В нём подробно описаны структура файлов, паттерны DTO/Guards и чек-лист добавления нового API.

Стандарты кода и правила коммитов
#

Мы используем Husky и lint-staged для проверки форматирования перед коммитом, а также следуем стандарту Conventional Commits:

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

Популярные типы:

  • feat: — новая функциональность
  • fix: — исправление ошибки
  • docs: — изменения в документации
  • refactor: — переписывание кода без изменения внешнего API
  • test: — добавление или исправление тестов

Пример: fix(core): resolve null pointer in user parsing

Оформление PR (Pull Request) запросов
#

  1. Убедитесь, что ваш PR направлен в ветку develop.
  2. В описании PR укажите, какую проблему решает данный PR (ссылка на Issue: Fixes #123).
  3. Не обновляйте версию в package.json и CHANGELOG.md — это делается централизованно при выпуске релиза.
  4. Перед отправкой убедитесь, что все проверки (pnpm typecheck, pnpm test, pnpm lint) проходят успешно.

Ищете, с чего начать?
#

Если вы хотите внести свой первый вклад в Metaform, но не знаете, какую задачу выбрать:

  1. Найдите подходящий Issue: Зайдите во вкладку Issues и отфильтруйте задачи по меткам (labels):
    • good first issue — небольшие изолированные задачи, идеальные для первого знакомства с кодовой базой.
    • help wanted — задачи, в которых проекту особенно нужна помощь сообщества.
  2. Забронируйте задачу: Напишите комментарий в выбранном Issue (например, “I’d like to work on this!”), чтобы мы закрепили его за вами. Это поможет избежать ситуаций, когда несколько человек параллельно делают одну и ту же работу.
  3. Свяжите PR с задачей: При создании Pull Request укажите ссылку на проблему в описании (Fixes #123 или Closes #123), чтобы Issue автоматически закрылся после мёрджа.

Предложения и не-кодовый вклад
#

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

Предложение нового функционала (Feature Request)
#

Если у вас есть идея новой возможности или предложения по улучшению API Metaform:

  1. Проверьте существующие Issues, чтобы убедиться, что идея ещё не обсуждается.
  2. Создайте новый Issue с типом Feature Request.
  3. В описании постарайтесь указать:
    • Проблему / Use Case: Зачем нужна эта фича? Какую реальную задачу она решает?
    • Предлагаемое решение: Как, по вашему мнению, должен выглядеть API или поведение библиотеки?
    • Альтернативы: Рассматривали ли вы другие способы решения этой задачи?

Улучшение документации
#

Нашли опечатку, неточность в описании типов или неработающий пример кода в README/документации?

  • Для мелких правок (опечатки, форматирование) можно сразу создавать Pull Request в ветку develop.
  • Для крупных изменений лучше предварительно создать Issue и обсудить структуру.

Ошибки: сообщение и исправление
#

Как сообщить о новой ошибке
#

Перед созданием темы в GitHub Issues:

  1. Проверьте дубликаты: Убедитесь через поиск, что баг ещё не описан. Если похожий Issue уже есть, дополните его своими деталями.
  2. Проверьте версию: Убедитесь, что проблема воспроизводится на последней версии Metaform.
  3. Подготовьте MRE: Предоставьте минимальный воспроизводимый пример (Minimal Reproducible Example).
  4. Укажите контекст:
    • Краткое описание проблемы;
    • Ожидаемое и фактическое поведение;
    • Минимальный код или конфигурация;
    • Версии Metaform, Node.js и среда выполнения и ее версия (если не используете Node.js)

Как предложить исправление зарегистрированной ошибки
#

Если вы нашли открытый Issue с багом и хотите его исправить:

  1. Забронируйте задачу: Напишите в комментариях к Issue, что берёте его в работу («I’d like to work on a fix for this!»), чтобы избежать дублирования работы с другими контрибуторами.
  2. Свяжите PR с проблемой: В описании Pull Request укажите ссылку на Issue (Fixes #123 или Closes #123), чтобы он автоматически закрылся при мёрдже.
  3. Добавьте регрессионный тест: К исправлению обязательно должен прилагаться тест в папке __tests__/. Он должен падать без вашего кода и успешно проходить с ним.
  4. Фокусируйтесь на главном: Не добавляйте в PR сторонний рефакторинг, форматирование чужого кода или новые фичи.
  5. Сохраняйте обратную совместимость: Исправление не должно ломать публичный API или текущее поведение библиотеки.

💡 Что такое регрессионный тест и как его написать?
#

Это не отдельная система тестирования, а обычный юнит-тест Vitest. Вы просто добавляете новый it(...) в существующий файл тестов в папке __tests__/ рядом с исправляемым файлом.

  1. Напишите тест, воспроизводящий сценарий из Issue (без ваших правок он должен падать).
  2. Внесите исправление в исходный код, чтобы тест стал успешным (pnpm test).
  3. Отправьте файл с новым тестом и ваш багфикс в одном Pull Request.

Обратите внимание: делать всё одним коммитом не обязательно. Отличная практика — сначала сделать коммит с падающим тестом (демонстрирующим ошибку), а следующим коммитом добавить исправление, делающее тест «зеленым».

Зоны ответственности
#

Что бы объяснить и разделить, кто формирует релиз, кто управляет окружением, принимает решения по какому пути идет развитие библиотеки, считаем необходимым объяснить зоны ответственности.

Мейнтейнер (Maintainer)
#

Отвечает за обслуживание кода, поддержание стабильности веток, принятие решений по Pull Request (Merge / Reject) и запуск релизов. Мейнтейнер контролирует кодовую базу целиком — от конфигурации инструментов и версий зависимостей до ревью стороннего кода.

Контрибутор (Contributor)
#

Добровольный разработчик, помогающий в развитии Metaform. Вы можете отправлять исправления кода, предлагать новые фичи, находить ошибки и улучшать документацию.

⚠️ Архитектурные и инфраструктурные изменения:
Сторонние разработчики могут предлагать улучшения архитектуры, инструментов или крупных зависимостей. Однако любые изменения, существенно влияющие на Metaform и её пользователей, должны предварительно обсуждаться в отдельном Issue, чтобы исключить неприятные побочные эффекты и избежать бесполезно потраченного времени на PR.

Безопасность (Security Policy)
#

Если вы обнаружили потенциальную уязвимость безопасности в Metaform, пожалуйста, не создавайте публичный Issue.

Используйте приватный механизм GitHub Security Advisories или свяжитесь с мейнтейнером напрямую, чтобы мы могли оперативно подготовить патч до разглашения информации.

Лицензия и авторство (License & Recognition)
#

  • Лицензия MIT: Metaform распространяется под лицензией MIT.
  • Согласие с лицензией: Отправляя Pull Request, вы подтверждаете, что ваш вклад будет опубликован на условиях лицензии MIT.
  • Признание авторов: Ваше имя (или никнейм GitHub) будет добавлено в файл CONTRIBUTORS в знак благодарности за помощь проекту.