# Подготовка сообщений коммитов

# Правила коммитов Git для языковых моделей ИИ

## Основные принципы

1. **Следуй Conventional Commits** (https://www.conventionalcommits.org/).
2. **Будь кратким и точным** — без витиеватого языка, превосходных степеней и ненужных прилагательных.
3. **Сосредоточься на том, ЧТО изменилось, а не КАК это работает** — описывай изменение, а не детали реализации.
4. **Одно логическое изменение на коммит** — разделяй связанные, но независимые изменения на отдельные коммиты.
5. **Пиши в повелительном наклонении** — «Добавь функцию», а не «Функция добавлена» или «Добавляет функцию».
6. **Всегда включай основной текст** — никогда не используй коммиты только с заголовком.

## Структура сообщения коммита

```
<type>(<scope>): <subject>

<body>

<footer>
```

### Тип — обязательно

- `feat`: новая функция.
- `fix`: исправление ошибки.
- `refactor`: изменение кода, которое не исправляет ошибку и не добавляет функцию.
- `perf`: повышение производительности.
- `style`: изменения стиля кода — форматирование, пропущенные точки с запятой и т. д.
- `test`: добавление или обновление тестов.
- `docs`: изменения документации.
- `build`: система сборки или внешние зависимости — npm, gradle, Xcode, SPM.
- `ci`: изменения конвейера CI/CD.
- `chore`: рутинные задачи — gitignore, конфигурационные файлы, сопровождение.
- `revert`: отмена предыдущего коммита.

### Область — необязательно, но рекомендуется

Указывает область изменения: `auth`, `ui`, `api`, `db`, `i18n`, `analytics` и т. д.

### Заголовок — обязательно

- **Не более 50 символов**.
- **Первая буква строчная**, если это не имя собственное.
- **Без точки в конце**.
- **Повелительное наклонение**: «добавь», а не «добавлено» или «добавляет».
- **Будь конкретен**: «добавь проверку email», а не «добавь проверку».

### Основной текст — обязательно

- **Всегда включай основной текст** — минимум 1 предложение.
- **Объясни, ЧТО изменилось и ПОЧЕМУ** — дай контекст.
- **Переноси строки на 72 символах**.
- **Отделяй от заголовка пустой строкой**.
- **Используй маркированные пункты для нескольких изменений** — `-` или `*`.
- **Ссылайся на номера задач**, если применимо.
- **Упоминай конкретные классы, функции и файлы, когда это уместно**.

### Подвал — необязательно

- **Несовместимые изменения**: `BREAKING CHANGE: <description>`.
- **Ссылки на задачи**: `Closes #123`, `Fixes #456`.
- **Соавторы**: `Co-Authored-By: Name <email>`.

## Запрещённые слова и выражения

**НИКОГДА не используй эти слова** — они расплывчаты, субъективны или преувеличены:

❌ Всеобъемлющий
❌ Надёжный
❌ Усовершенствованный
❌ Улучшенный, если не указано, какой показатель улучшился
❌ Оптимизированный, если не указано, какой показатель улучшился
❌ Лучший
❌ Крутой
❌ Отличный
❌ Потрясающий
❌ Мощный
❌ Бесшовный
❌ Элегантный
❌ Чистый
❌ Современный
❌ Продвинутый

## Хорошие и плохие примеры

### ❌ ПЛОХО — нет основного текста
```
feat(auth): добавь вход по email и паролю
```

**Проблемы:**
- Нет основного текста.
- Не объясняется, что именно реализовано.

### ❌ ПЛОХО — расплывчатый основной текст
```
feat: Добавь крутую новую функцию входа

Этот коммит добавляет мощную новую систему входа с надёжной аутентификацией
и усовершенствованными возможностями безопасности. Реализация чистая и современная.
```

**Проблемы:**
- Субъективные прилагательные: крутой, мощный, надёжный, усовершенствованный, чистый, современный.
- Не указано, что добавлено.
- Основной текст описывает качество, а не функциональность.

### ✅ ХОРОШО
```
feat(auth): добавь вход по email и паролю с Firebase

Реализуй процесс входа с Firebase Authentication. Теперь пользователи могут
входить по email и паролю. Включает клиентскую проверку email и обработку
ошибок при сбоях сети и неверных учётных данных.
```

**Почему это хорошо:**
- Упомянута конкретная технология — Firebase.
- Понятная область — auth.
- Основной текст описывает добавленную функциональность.
- Объясняет, какие случаи охватывает обработка ошибок.

---

### ❌ ПЛОХО — нет основного текста
```
fix(auth): исключи двойное нажатие кнопки входа
```

**Проблемы:**
- Нет основного текста, объясняющего исправление.

### ✅ ХОРОШО
```
fix(auth): исключи двойное нажатие кнопки входа

Отключи кнопку входа после первого нажатия, чтобы предотвратить повторные
запросы аутентификации при нескольких быстрых нажатиях. Кнопка снова
включается после завершения аутентификации или ошибки.
```

**Почему это хорошо:**
- Повелительное наклонение.
- Описана конкретная проблема.
- Основной текст объясняет и проблему, и подход к решению.

---

### ❌ ПЛОХО
```
refactor(auth): выдели вспомогательные функции

Сделай код лучше и удобнее в сопровождении, выделив функции.
```

**Проблемы:**
- Субъективность — лучше, удобнее в сопровождении.
- Не указано, о каких функциях идёт речь.

### ✅ ХОРОШО
```
refactor(auth): вынеси вспомогательные функции в статические методы структуры

Преобразуй приватные функции randomNonceString и sha256 в статические методы
структуры AppleSignInHelper для лучшей организации кода и пространств имён.
```

**Почему это хорошо:**
- Описано конкретное изменение.
- Упомянуты точные имена функций.
- Основной текст объясняет причины и новую структуру.

---

### ❌ ПЛОХО
```
feat(i18n): добавь локализацию
```

**Проблемы:**
- Нет основного текста.
- Слишком расплывчато.

### ✅ ХОРОШО
```
feat(i18n): добавь английский и турецкий переводы экрана входа

Создай String Catalog с английскими и турецкими переводами элементов
интерфейса входа, оповещений и ошибок аутентификации. Охватывает все строки
для пользователей в LoginView, LoginViewController и AuthService.
```

**Почему это хорошо:**
- Указаны конкретные языки.
- Понятная область — i18n.
- Основной текст перечисляет, что переведено и в каких файлах.

---

## Правила коммитов для нескольких файлов

### Когда разделять коммиты

Разделяй изменения на отдельные коммиты, когда они затрагивают:

1. **Разные логические задачи**
   - ✅ Коммит 1: добавь функцию.
   - ✅ Коммит 2: добавь тесты для функции.

2. **Разные области**
   - ✅ Коммит 1: `feat(ui): добавь компонент кнопки`.
   - ✅ Коммит 2: `feat(api): добавь конечную точку для действия кнопки`.

3. **Разные типы**
   - ✅ Коммит 1: `feat(auth): добавь форму входа`.
   - ✅ Коммит 2: `refactor(auth): выдели логику проверки`.

### Когда объединять коммиты

Объединяй изменения в одном коммите, когда это:

1. **Тесно связанные изменения**
   - ✅ Добавление функции и её использования в том же компоненте.

2. **Атомарное изменение**
   - ✅ Переименование функции в нескольких файлах.

3. **Изменения, неработоспособные друг без друга**
   - ✅ Одновременное добавление интерфейса и его реализации.

## Стратегия коммитов на уровне файла

### Пример: изменения LoginView

Если в LoginView есть 2 независимых изменения:

**Изменение 1:** рефакторинг структуры stack view.
**Изменение 2:** добавление индикатора загрузки.

**Раздели на 2 коммита:**

```
refactor(ui): вынеси stack view содержимого в свойство представления входа

Замени встроенную инициализацию stack view подходом на основе свойства
для лучшей организации кода и повторного использования. Определение
stack view переносится из метода setupUI в ленивое свойство.
```

```
feat(ui): добавь состояние загрузки с индикатором активности в представление входа

Добавь слой с индикатором загрузки и метод setLoading для отключения
взаимодействия и затемнения содержимого при аутентификации. Значение alpha
содержимого при загрузке уменьшается до 0.5.
```

## Специальные правила локализации

### ✅ ХОРОШО
```
feat(i18n): добавь английский и турецкий переводы

Создай String Catalog (Localizable.xcstrings) с английскими и турецкими
переводами всех строк экрана входа, сообщений об ошибках и оповещений.
```

```
build(i18n): добавь поддержку турецкой локализации

Добавь турецкий язык в локализации проекта и включи генерацию String Catalog
(SWIFT_EMIT_LOC_STRINGS) в настройках сборки конфигураций Debug и Release.
```

```
feat(i18n): локализуй элементы интерфейса представления входа

Замени жёстко заданные строки в LoginView на NSLocalizedString для заголовка,
подзаголовка, подписей, заполнителей и названий кнопок. Теперь весь текст
для пользователей поддерживает локализацию.
```

### ❌ ПЛОХО
```
feat: Добавь всеобъемлющую многоязычную поддержку

Добавь в приложение крутую систему локализации.
```

```
feat: Добавь переводы
```

## Несовместимые изменения

При внесении несовместимых изменений:

```
feat(api): измени структуру ответа аутентификации

Конечная точка аутентификации теперь возвращает объект пользователя в поле
'data', а не на корневом уровне. Это позволяет добавлять в ответ метаданные.

BREAKING CHANGE: Обнови все клиенты API: обращайся к response.data.user
вместо response.user.

Руководство по миграции:
- До: const user = response.user
- После: const user = response.data.user
```

## Порядок коммитов

При подготовке нескольких коммитов упорядочивай их логично:

1. **Сначала зависимости**: добавляй библиотеки и конфигурации до их использования.
2. **Основа перед функциями**: модели перед представлениями.
3. **Сборка перед исходниками**: конфигурации сборки перед изменениями кода.
4. **Утилиты перед потребителями**: вспомогательные компоненты перед теми, которые их используют.

### Пример порядка:

```
1. build(auth): добавь право доступа Sign in with Apple
   Добавь файл entitlements с возможностью Sign in with Apple для включения
   аутентификации через Apple ID.

2. feat(auth): добавь криптографические помощники Apple Sign-In
   Добавь служебные функции генерации случайного nonce и хеширования SHA256,
   необходимые для процесса аутентификации Apple Sign-In.

3. feat(auth): добавь аутентификацию Apple Sign-In в AuthService
   Добавь метод signInWithApple в протокол AuthService и его реализацию.
   Использует учётные данные OAuthProvider с idToken и nonce для
   аутентификации Firebase.

4. feat(auth): добавь процесс Apple Sign-In в модель представления входа
   Реализуй метод loginWithApple в LoginViewModel для обработки
   аутентификации Apple с idToken, nonce и fullName.

5. feat(auth): реализуй процесс авторизации Apple Sign-In
   Добавь методы делегата ASAuthorizationController для обработки
   авторизации Apple Sign-In, проверки учётных данных и обработки ошибок.
```

## Особые случаи

### Конфигурационные файлы

```
chore: исключи GoogleService-Info.plist из контроля версий

Добавь GoogleService-Info.plist в .gitignore, чтобы не сохранять в коммитах
конфигурацию Firebase с API-ключами.
```

```
build: обнови целевую версию развёртывания iOS до 15.0

Измени минимальную версию iOS с 14.0 на 15.0 для поддержки синтаксиса
async/await в процессах аутентификации.
```

```
ci: добавь рабочий процесс GitHub Actions для тестирования

Добавь рабочий процесс запуска модульных тестов для pull request.
Он выполняется на последней macOS с Xcode 15.
```

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

```
docs: добавь руководство по аутентификации API

Задокументируй процесс настройки Firebase Authentication, включая шаги
настройки Google Sign-In и Apple Sign-In.
```

```
docs: обнови README, добавив шаги установки

Добавь инструкции по установке зависимостей SPM и руководство по настройке Firebase.
```

### Рефакторинг

```
refactor(auth): преобразуй вспомогательные функции в статические методы структуры

Помести вспомогательные функции Apple Sign-In в структуру AppleSignInHelper
со статическими методами для лучшей организации кода и пространств имён.
randomNonceString и sha256 преобразуются из приватных функций в статические методы.
```

```
refactor(ui): вынеси проверку email в отдельный метод

Перенеси логику проверки email регулярным выражением из loginWithEmail
в метод isValidEmail для повторного использования и удобства тестирования.
```

### Производительность

**Укажи конкретное улучшение:**

❌ `perf: оптимизируй вход`

✅
```
perf(auth): сократи время запроса входа с 2 с до 500 мс

Добавь кэширование запросов конфигурации Firebase, чтобы избежать
повторных сетевых вызовов. Теперь конфигурация кэшируется после первого получения.
```

## Требования к основному тексту

**Минимальные требования к основному тексту:**

1. **Как минимум 1–2 полных предложения**.
2. **Конкретно опиши, ЧТО изменилось**.
3. **Объясни, ПОЧЕМУ изменение было необходимо, если это неочевидно**.
4. **Упоминай затронутые компоненты и файлы, когда уместно**.
5. **Включай технические детали, которые неочевидны из заголовка**.

### Хорошие примеры основного текста:

```
Добавь слой с индикатором загрузки и метод setLoading для отключения
взаимодействия пользователя и затемнения содержимого при аутентификации.
```

```
Обнови метод signInWithApple для приёма параметра fullName и используй
appleCredential для правильного создания профиля пользователя в Firebase.
```

```
Замени жёстко заданные строки на NSLocalizedString в LoginView для заголовка,
подписей, заполнителей и кнопок. Теперь весь текст интерфейса поддерживает
английский и турецкий переводы.
```

### Плохие примеры основного текста:

❌ `Добавь функцию.` — слишком расплывчато.
❌ `Файлы обновлены.` — не объясняется, что именно.
❌ `Исправление ошибки.` — не объясняется, какой ошибки.
❌ `Рефакторинг.` — не объясняется, что подверглось рефакторингу.

## Шаблон для ИИ-моделей

Когда ИИ-модель просят создать коммиты:

```
1. Прочитай git diff, чтобы понять ВСЕ изменения
2. Сгруппируй изменения по логическим задачам
3. Упорядочь коммиты по зависимостям
4. Для каждого коммита:
   - Выбери подходящие тип и область
   - Напиши конкретный краткий заголовок — максимум 50 символов
   - Напиши подробный основной текст — минимум 1–2 предложения, обязательно
   - Используй повелительное наклонение
   - Избегай запрещённых слов
   - Сосредоточься на том, ЧТО изменилось и ПОЧЕМУ
5. Формат результата:
   ## Коммит [N]

   **Заголовок:**
   ```
   type(scope): subject
   ```

   **Описание:**
   ```
   Основной текст, объясняющий, что изменилось и почему. Упомяни конкретные
   затронутые компоненты, классы или методы. Дай контекст.
   ```

   **Файлы для добавления:**
   ```bash
   git add path/to/file
   ```
```

## Итоговый чек-лист

Прежде чем предложить коммит, проверь:

- [ ] Тип правильный — feat/fix/refactor/и т. д.
- [ ] Область конкретна и осмысленна.
- [ ] Заголовок в повелительном наклонении.
- [ ] В заголовке ≤50 символов.
- [ ] **Основной текст присутствует — обязательно**.
- [ ] **В основном тексте как минимум 1–2 полных предложения**.
- [ ] Основной текст объясняет ЧТО и ПОЧЕМУ.
- [ ] Нет запрещённых слов.
- [ ] Нет субъективных прилагательных.
- [ ] Конкретно указано, ЧТО изменилось.
- [ ] Упомянуты затронутые компоненты и файлы.
- [ ] На коммит приходится одно логическое изменение.
- [ ] Файлы сгруппированы правильно.

---

## Пример сообщения коммита — полный

```
feat(auth): добавь проверку email в форму входа

Реализуй клиентскую проверку email регулярным выражением перед отправкой
запроса аутентификации. Проверяет соответствие стандартному формату email
(user@domain.ext) и показывает сообщение об ошибке при неверном вводе.
Предотвращает ненужные вызовы API Firebase для некорректных адресов email.
```

**Почему это хорошо:**
- Понятные тип и область.
- Конкретный заголовок.
- Основной текст объясняет, что делает проверка.
- Основной текст объясняет, почему она нужна.
- Упомянута польза — предотвращение вызовов API.
- Нет запрещённых слов.
- Повелительное наклонение во всём тексте.

---

**Помни:** хорошее сообщение коммита должно позволять понять изменение без просмотра diff. Будь конкретен, краток и объективен, всегда включай содержательный основной текст.

---
Источник: prompts.chat. Текст: CC0 1.0 Universal. Русская версия: Kvantora.
