Работа с Git-репозиторием

Модель ветвления: GitFlow

В проекте используется GitFlow - классическая модель ветвления для упорядоченной разработки и релизного цикла.

main
|
dev
|
feature/`номер-задачи`
|
feature/`номер_корневой_задачи`-`номер_подзадачи`

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

Примечание: прямые коммиты разрешены для начальной настройки репозитория/фрэймворка/структуры проекта

Вспомогательные ветки

Правила именования веток

Формат для feature-веток

• feature-номер_задачи
• feature-номер_корневой_задачи-номер_подзадачи

Примеры:

• feature-10 - основная задача
• feature-10-21 - подзадача(оформлена как отдельная задача в трекере)
• feature-10-21-01 - подзадача задачи/подзадачи (не оформленная в трекере)

Формат для hotfix-веток

• hotfix-краткое-описание-проблемы

Примеры:

• hotfix-fix-auth-redirect
• hotfix-critical-db-connection

Процесс разработки

1. Начало работы над задачей

# Переключиться на актуальную dev
git checkout dev
git pull origin dev

# Создать feature-ветку
git checkout -b feature-10

# Для подзадачи (если нужно)
git checkout -b feature-10-21

# Для декомпозиции задачи/подзадачи (если нужно)
git checkout -b feature-10-21-01
git checkout -b feature-10-21-02

2. В процессе разработки

# Регулярно синхронизируемся с dev
git checkout dev
git pull origin dev
git checkout feature-10-21
git rebase dev


# Или через merge (если вам нужен явный коммит синхронизации)
git merge dev

3. Подготовка к слиянию в dev

Требования перед созданием Pull Request:

• ✅ Код покрыт unit-тестами
• ✅ Все тесты проходят: composer test
• ✅ Статический анализ проходит: vendor/bin/phpstan analyse --level=8 src
• ✅ Нет конфликтов с целевой веткой dev

Pull Request (PR) процесс

Создание PR

1. Пуш ветки в удалённый репозиторий:

    git push origin <feature-10> <- ваша ветка
   

2. Создание PR через интерфейс GitHub:
   • Base: dev
   • Compare: <feature-10> <- ваша ветка
   • Title: Краткое описание задачи
   • Description: Подробное описание изменений, ссылка на задачу в трекере(не обязательно)
3. Назначить ревьюеров (минимум 1 разработчика)

Требования к PR

• Заголовок должен отражать суть изменений
• В описании указать:
  • Что было сделано
  • Как тестировалось
  • Особые моменты для ревью
  • Ссылка на задачу в трекере Пример: #10(Опционально)
• PR желательно делать оптимального для ревью размера в районе 400-800 строк кода

Процесс ревью

1. Ревьюеры проверяют:
   • Соответствие архитектуре (чистая архитектура, DDD, CQRS)
   • Качество кода
   • Покрытие тестами
   • Отсутствие регрессий
2. Замечания исправляются в той же ветке:

    git add .
    git commit -m "fix: исправление замечаний ревью"
    git push origin feature-10
   

3. После всех апрувов PR может быть замёржен

Стратегия слияния (Merge strategy)

Для feature-веток в dev

Используется: Squash and merge

feature-10 (несколько коммитов) -> 1 коммит в dev

Почему?

• Чистая история в dev
• Легко откатить фичу целиком
• Каждая фича представлена одним логическим коммитом
• Удобно для генерации changelog

Правила коммитов

Используем Conventional Commits:

Или другой формат не противоречащий здравому смыслу и разграничению коммитов на логичные группы(см. предыдущие коммиты репозитория)

#task_num <type>(<scope>): <description>

[optional body]

[optional footer]

Типы (type):

• feat - новая функциональность
• fix - исправление ошибки
• docs - документация
• style - форматирование кода (без изменения логики)
• refactor - рефакторинг
• test - добавление или исправление тестов
• chore - обслуживание (обновление зависимостей и т.п.)

  Примеры:

  feat(analytics): добавить отчёт по задачам
  fix(auth): исправить валидацию JWT токена
  test(clients): добавить тесты для создания клиента
  refactor(core): оптимизировать работу с DTO
  

  Запрещено

  ❌ Прямые коммиты в dev и main

Никто не должен коммитить напрямую в защищённые ветки. Даже исправление опечатки - через PR.

Примечание: прямые коммиты разрешены для начальной настройки репозитория/фрэймворка/структуры проекта

❌ Force push в общие ветки

git push --force запрещён в dev и main. В feature-ветках - с осторожностью, только если работаете один.

❌ Сливать свои PR самостоятельно

PR должен замёржить ревьюер или ответственный за интеграцию, если не оговорено иное.

Автоматизация и CI/CD

Проверки при push (GitHub Actions)

При создании PR и push в ветку автоматически запускаются:

Статус проверок

• ✅ Все проверки прошли - можно мёржить
• ❌ Любая проверка упала - мёржить нельзя

Типовые сценарии

Начало новой задачи

git checkout dev
git pull origin dev
git checkout -b feature-10

Подзадача

git checkout feature-10
git checkout -b feature-10-21  # подзадача c номером 21

Декомпозиция задачи/подзадачи

git checkout feature-10-21
git checkout -b feature-10-21-01  # подзадача 1
git checkout -b feature-10-21-02  # подзадача 2

Синхронизация с dev

git checkout dev
git pull origin dev
git checkout feature/10-21
git rebase dev
# или
git merge dev

Исправление замечаний ревью

git add .
git commit -m "fix: исправление замечаний ревью"
git push origin feature-10

Отмена последнего коммита (в своей ветке)

git reset --soft HEAD~1  # изменения остаются в working directory
git reset --hard HEAD~1  # полное удаление коммита (осторожно!)

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

• Код покрыт unit-тестами
• Все тесты проходят локально
• Ветка синхронизирована с dev
• Описание PR заполнено
• Добавлена ссылка на задачу (в коммитах относящихся к ней или в описании PR)
• Назначены ревьюеры

Важно: Все изменения, включая документацию, проходят одинаковый процесс ревью.
Если вы правите ./docs/ – создавайте отдельную ветку и PR, как для кода.