Recommendations: Полезные дополнения

Руководство по написанию коммитов

Хорошо написанные коммиты — это ключ к понятной истории изменений проекта.
Грамотно написанные коммиты

  • Упрощают понимание истории изменений

  • Помогают при отладке (git bisect)

  • Удобны для автоматической генерации CHANGELOG.md

  • Облегчают работу всей команды

См. также

Подробнее см. соглашение о написании коммитов

🔤 Формат сообщения коммита

<type>: <краткое описание>

Причина изменения:
Что было изменено:
Как это реализовано:
Затронутые компоненты:
Ссылки:
Breaking changes:

Типы коммитов

Тип

Описание

feat

Новая фича

fix

Исправление бага

chore

Небольшие правки (обновление зависимостей, форматирование)

docs

Изменения в документации

style

Изменения стиля кода (отступы, форматирование)

refactor

Рефакторинг без изменения поведения

perf

Оптимизация производительности

test

Добавление или исправление тестов

build

Сборка или внешние зависимости

ci

CI/CD конфигурации

revert

Откат предыдущего коммита

Примеры хороших и плохих коммитов

Тип коммита

Хороший пример

Плохой пример

Причина

Новая функциональность

feat: добавить авторизацию через Google

update

Слишком общее, не понятно, что именно обновлено.

Исправление ошибки

fix: обработать ошибку при отсутствии токена в заголовках
«В некоторых случаях запросы без Authorization заголовка приводили к Internal Server Error. Теперь возвращается 401 Unauthorized.»

fixed bug

Не указано, какой именно баг был исправлен.

Оптимизация

perf: оптимизировать SQL-запросы в модуле пользователей
«Уменьшено количество обращений к БД с 15 до 3 на странице профиля.»

some changes

Очень общее описание, не уточняется, что конкретно изменилось.

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

docs: обновить README.md с новыми инструкциями по запуску

wip

Не информативно и не завершено. «WIP» — рабочий процесс, но коммит должен быть завершённым.

Тестирование

test: добавить unit-тесты для utils.py

merge branch

Не указывает, что было сделано с кодом, просто техническое действие без описания изменений.

CI/CD

ci: добавить workflow для проверки типов в GitHub Actions

some changes

Слишком общее сообщение, не говорит, что было изменено или добавлено в CI/CD.

💡 Полезные практики

  1. Делай коммиты по ходу работы Разделяй изменения на логичные шаги. Это помогает легче отслеживать изменения и откатывать их при необходимости. Коммить часто и по существу.

  2. Используй git commit –amend перед push. Если ты заметил ошибку в последнем коммите (описание или сам код), исправь его перед отправкой в удалённый репозиторий, чтобы история была чистой и без лишних исправлений.

  3. Используй git rebase -i для чистой истории. Применяй интерактивный ребейз, чтобы очистить историю перед пушем. Это поможет избежать множества merge-коммитов и сохранить линейную историю изменений.

  4. Используй четкие и информативные сообщения, даже если работаешь один. Чистая и понятная история коммитов полезна не только для других разработчиков, но и для тебя в будущем. Поддерживай структурированность и чёткость.

  5. Делай подробное описание, если изменение сложное или неочевидное. Подробное описание помогает не только тебе, но и твоим коллегам в будущем. Если изменения нетривиальные или касаются бизнес-логики — всегда поясняй «что», «почему» и «как».

✅ Чек-лист: Хороший ли твой коммит?

✅ Есть ли префикс типа (feat, fix, docs)? Префикс чётко указывает на тип изменений и помогает фильтровать коммиты по их предназначению.

✅ Краткое описание чётко объясняет, что было сделано? Описание должно быть лаконичным, но полным, чтобы без лишних слов было понятно, что конкретно было изменено.

✅ Подробное описание объясняет почему изменения необходимы? Если изменение нетривиальное, добавь пояснения, чтобы другим (и тебе в будущем) было понятно, зачем оно было сделано.

✅ Сообщение не содержит лишних деталей или мусора? Избегай технических подробностей, которые не относятся к суть изменений. Всё, что не помогает понять логику изменений, следует исключить.

✅ Если это крупное изменение, есть ли ссылка на задачу или issue? Всегда добавляй ссылку на задачу или issue в случае значительных изменений. Это поможет быстро понять контекст изменений и при необходимости вернуться к обсуждению задачи.

Основы работы с MyST Markdown

Это поможет красиво оформлять документацию

См. также

Подробнее см. документацию MyST Parser

Адмониции

Под каждой адмоницией есть блок текста, который можно скопировать и использовать в своей документации

attention — Внимание

ВНИМАНИЕ

Пожалуйста, проверьте настройки перед запуском.

```{admonition} ВНИМАНИЕ
:class: attention

Пожалуйста, проверьте настройки перед запуском.
```

note — Примечание

Примечание

Это примечание содержит важную, но не критическую информацию.

```{admonition} Примечание
:class: note

Это примечание содержит важную, но не критическую информацию.
```

warning — Предупреждение

Предупреждение

Эта операция может привести к потере данных.

```{admonition} Предупреждение
:class: warning

Эта операция может привести к потере данных.
```

tip — Совет

Совет

Попробуйте использовать --dry-run перед запуском.

```{admonition} Совет
:class: tip

Попробуйте использовать `--dry-run` перед запуском.
```

seealso — См. также

См. также

Для дополнительной информации см. раздел [Создание бэкапов].

```{admonition} См. также
:class: seealso

Для дополнительной информации см. раздел [Создание бэкапов].
```

🔍 hint — Подсказка

Подсказка

Попробуйте ввести команду help для получения списка действий.

```{admonition} Подсказка
:class: hint

Попробуйте ввести команду `help` для получения списка действий.
```

important — Важно

Важно

Не забудьте сохранить конфигурацию перед перезагрузкой.

```{admonition} Важно
:class: important

Не забудьте сохранить конфигурацию перед перезагрузкой.
```

custom — Произвольный заголовок

Пользовательский заголовок

Это адмониция с пользовательским названием и стилем.

```{admonition} Пользовательский заголовок
:class: custom

Это адмониция с пользовательским названием и стилем.
```