Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
198 lines (138 loc) · 7.75 KB

CONTRIBUTING.md

File metadata and controls

198 lines (138 loc) · 7.75 KB
Raw

Вклад в проект

Спасибо, что хотите помочь! Ниже — краткие правила для успешного PR.

Как начать

  1. Убедитесь, что есть issue с описанием задачи или создайте его.

  2. Ответвитесь от актуальной main:

git checkout main
git pull origin main
git checkout -b feature/краткое-имя-задачи
  1. Имя ветки должно соответствовать шаблону:
{тип}/{краткое-описание}

Основные типы веток:

  • feature/ — добавление нового функционала
  • fix/ — исправление ошибок
  • hotfix/ — срочные исправления в основной ветке
  • docs/ — обновление документации
  • refactor/ — рефакторинг кода без изменения функциональности
  • test/ — добавление или исправление тестов
  • ci/ — изменения CI/CD и инфраструктурных файлов
  1. Держите ветку в актуальном состоянии.

Перед открытием PR и при длительной работе подтяните изменения из main:

git fetch origin
git merge origin/main

Важно: на момент отправки PR ветка должна быть синхронизирована с актуальным main, иначе могут не пройти rule checks / CI.

Код-стайл и коммиты

Проект написан на .NET.

Перед отправкой PR код должен:

  • собираться в Release конфигурации;
  • проходить анализаторы без предупреждений;
  • проходить тесты;
  • не снижать покрытие тестами без причины.

Коммиты рекомендуется писать в стиле Conventional Commits или в коротком понятном формате:

[add]: add delete account outbox event
[fix]: handle revoked refresh token
[docs]: update README
[test]: cover outbox publisher
[refactor]: split outbox publisher base

Локальные проверки перед PR

Перед отправкой PR желательно выполнить те же проверки, которые запускаются в CI.

Build

dotnet build Planara.Auth.sln \
  --no-restore \
  -c Release \
  /p:RunAnalyzersDuringBuild=true \
  /p:TreatWarningsAsErrors=true

Tests

Для запуска интеграционных тестов требуется Docker, так как тесты используют Testcontainers.

rm -rf tests/TestResults

dotnet test Planara.Auth.sln \
  -c Release \
  --collect:"XPlat Code Coverage" \
  --settings tests/coverlet.runsettings \
  --results-directory ./tests/TestResults \
  -v:n

Сборка и проверки в CI

Pull request считается готовым к review, если проходят основные проверки:

  • dotnet build
  • dotnet test
  • сбор покрытия тестов
  • проверки GitHub Actions
  • указан type label
  • указан release label: major, minor, patch или no-release

Если CI падает, сначала исправьте причину падения в своей ветке, затем обновите PR.

Как оформить PR

В описании PR укажите:

  • что изменено;
  • почему это нужно;
  • какие сценарии проверены;
  • связанный issue, если есть;
  • type label;
  • release label: major, minor, patch или no-release.

Для связи с issue используйте:

Closes #<номер>

или укажите связь через поле Development.

Labels

Для PR используются два типа labels:

  • labels типа изменения — описывают, что именно меняется;
  • release labels — определяют, будет ли выпущена новая версия и какой тип обновления будет применен.

Type labels

Type label описывает характер изменения в PR или issue.

Доступные type labels:

  • bug — исправление ошибки или неработающего поведения
  • documentation — изменения или дополнения документации
  • duplicate — issue или pull request уже существует
  • enhancement — новая функциональность или улучшение существующей логики
  • good first issue — задача, подходящая для первого вклада
  • help wanted — требуется дополнительное внимание или помощь
  • invalid — issue или PR некорректен или неактуален
  • question — требуется дополнительная информация
  • wontfix — задача не будет выполняться

Для обычного PR чаще всего используются:

  • enhancement — для новой функциональности;
  • bug — для исправления ошибки;
  • documentation — для изменений документации.

Release labels

Release label определяет, как PR влияет на версию сервиса.

Доступные release labels:

  • major — мажорное обновление, несовместимое с предыдущей версией
  • minor — минорное обновление, новая функциональность без breaking changes
  • patch — patch-обновление, исправление ошибок или небольшие безопасные правки
  • no-release — изменения без выпуска новой версии

Release label используется CI/CD для автоматического обновления версии, создания git tag и публикации Docker image в GHCR.

Если PR не должен приводить к выпуску новой версии, используйте:

no-release

Примеры labels

  • новая mutation, endpoint или значимая фича — enhancement + minor
  • breaking change в GraphQL API или Kafka message contract — enhancement + major
  • исправление ошибки — bug + patch
  • обновление README / CONTRIBUTING — documentation + no-release
  • рефакторинг без изменения runtime-поведения — enhancement + no-release

Чек-лист перед отправкой

  • Ветка создана от актуальной main
  • Ветка синхронизирована с main
  • dotnet build проходит локально
  • dotnet test проходит локально
  • Новая логика покрыта тестами
  • Документация обновлена, если изменилось поведение API
  • PR описан понятно и связан с issue, если issue есть
  • Указан type label
  • Указан release label: major, minor, patch или no-release

Коммуникация

Вопросы, предложения и обсуждения — в Issues или Discussions.

Пожалуйста, соблюдайте Кодекс поведения.