## Recommendations: Полезные дополнения ### Руководство по написанию коммитов Хорошо написанные коммиты — это ключ к понятной истории изменений проекта. Грамотно написанные коммиты - Упрощают понимание истории изменений - Помогают при отладке (`git bisect`) - Удобны для автоматической генерации `CHANGELOG.md` - Облегчают работу всей команды ```{seealso} Подробнее см. [соглашение о написании коммитов](https://www.conventionalcommits.org/ru/v1.0.0/) ``` --- #### 🔤 Формат сообщения коммита ```text : <краткое описание> Причина изменения: Что было изменено: Как это реализовано: Затронутые компоненты: Ссылки: 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 Это поможет красиво оформлять документацию ```{seealso} Подробнее см. документацию [MyST Parser](https://myst-parser.readthedocs.io/en/stable/index.html) ``` #### Адмониции Под каждой адмоницией есть блок текста, который можно скопировать и использовать в своей документации ##### `attention` — Внимание ```{admonition} ВНИМАНИЕ :class: attention Пожалуйста, проверьте настройки перед запуском. ``` ````text ```{admonition} ВНИМАНИЕ :class: attention Пожалуйста, проверьте настройки перед запуском. ``` ```` ##### `note` — Примечание ```{admonition} Примечание :class: note Это примечание содержит важную, но не критическую информацию. ``` ````text ```{admonition} Примечание :class: note Это примечание содержит важную, но не критическую информацию. ``` ```` ##### `warning` — Предупреждение ```{admonition} Предупреждение :class: warning Эта операция может привести к потере данных. ``` ````text ```{admonition} Предупреждение :class: warning Эта операция может привести к потере данных. ``` ```` ##### `tip` — Совет ```{admonition} Совет :class: tip Попробуйте использовать `--dry-run` перед запуском. ``` ````text ```{admonition} Совет :class: tip Попробуйте использовать `--dry-run` перед запуском. ``` ```` ##### `seealso` — См. также ```{admonition} См. также :class: seealso Для дополнительной информации см. раздел [Создание бэкапов]. ``` ````text ```{admonition} См. также :class: seealso Для дополнительной информации см. раздел [Создание бэкапов]. ``` ```` ##### 🔍 `hint` — Подсказка ```{admonition} Подсказка :class: hint Попробуйте ввести команду `help` для получения списка действий. ``` ````text ```{admonition} Подсказка :class: hint Попробуйте ввести команду `help` для получения списка действий. ``` ```` ##### `important` — Важно ```{admonition} Важно :class: important Не забудьте сохранить конфигурацию перед перезагрузкой. ``` ````text ```{admonition} Важно :class: important Не забудьте сохранить конфигурацию перед перезагрузкой. ``` ```` ##### `custom` — Произвольный заголовок ```{admonition} Пользовательский заголовок :class: custom Это адмониция с пользовательским названием и стилем. ``` ````text ```{admonition} Пользовательский заголовок :class: custom Это адмониция с пользовательским названием и стилем. ``` ```` ##### `dropdown` — Сворачиваемый блок ```{admonition} Показать дополнительные параметры :class: dropdown Скрытые параметры: - `--verbose` - `--debug` ``` ````text ```{admonition} Показать дополнительные параметры :class: dropdown Скрытые параметры: - `--verbose` - `--debug` ``` ````