Процесс добавления нового кода в проект в большинстве команд может быть не всегда стандартизирован. Из-за этого могут возникнуть сложности в коммуникации разработчиков как на уровне описания добавленного кода, так и понимания, какое влияние несет новый функционал на сам проект. Кроме того, команде аналитиков, разработчиков и заказчикам проекта важно иметь описание хронологии изменений проекта в читабельном виде.
Поэтому решил написать статью, в которой хотелось бы затронуть тему стандартизации процесса, используя конвенции и различные инструменты, позволяющие соблюсти правильное и понятное развитие кода проекта, что и применяется в нашей компании. Статья может быть полезна всем тем, кто ведет проекты в git.
Стандартная процедура добавления нового функционала в проект выглядит так:
В процедуре возникает ряд вопросов:
или Зарегистрируйся — это инструмент, который проверяет сообщения commit-ов на соответствие общепринятым стандартам их описаний. Введение таких стандартов описаний сообщений в общую практику было необходимо, чтобы не засорять проект commit-ами, имеющими хаотичную структуру описания. Такие commit-ы не всегда могут быть понятными как с точки зрения тематики, так и с точки зрения их степени влияния на проект.
В случае, если вы пытаетесь произвести commit с сообщением(commit-message), не соответствующим стандарту (только если вы не внесли дополнительные изменения в файл конфигурации), инструмент сommitlint его блокирует. Теперь commit не может быть внесен на локальный репозиторий, либо на удаленный GitLab instance-сервер, что позволяет исключить человеческий фактор некорректного заполнения commit-сообщений, структурное и полное написание которых зачастую игнорируются.
Напомню, что некорректное заполнение commit-сообщений может привести к сложностям для понимания и поддержки проекта не только другими разработчиками, но и автору проекта, ввиду того, что внесенные изменения со временем могут забываться.
Запускается инструмент commitlint как husky pre-commit hook, то есть локально на сервере, с которого автор хочет произвести отправку сommit-а на удаленный gitlab-сервер.
Структура составления сообщения в commit-е должна выглядеть следующим образом:
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
Так выглядит пример commit-сообщения в соответствии с конвенцией описания:
feat(model): Add new OCR model which shows better performance on validation set
Ниже представлена таблица с описанием того, какие типы (название <type> в конвенции выше) использовать в случае добавления нового commit-а:
Type
Description
feat
A new feature
fix
A bug fix
docs
Documentation only changes
style
Changes that do not affect the meaning of the code (white-space, formatting etc)
refactor
A code change that neither fixes a bug nor adds a feature
perf
A code change that improves performance
test
Adding missing tests or correcting existing tests
build
Changes that affect the build system or external dependencies
ci
Changes to our CI configuration files and scripts
chore
Other changes that don't modify src or test files
revert
Reverts a previous commit
Поэтому решил написать статью, в которой хотелось бы затронуть тему стандартизации процесса, используя конвенции и различные инструменты, позволяющие соблюсти правильное и понятное развитие кода проекта, что и применяется в нашей компании. Статья может быть полезна всем тем, кто ведет проекты в git.
Стандартная процедура добавления нового функционала в проект выглядит так:
- Разработчик делает клонирование проекта из центрального хранилища на локальную машину.
- Создает новую ветку и вносит новый commit на локальном репозитории.
- Делает push ветки в центральное хранилище.
- Делает merge request данной ветки в main(or master).
- Происходит новый релиз проекта.
В процедуре возникает ряд вопросов:
- как сделать автопроверку добавления некорректного описанного commit-а(commit-message) локально, чтобы впоследствии он не был добавлен в удаленное централизованное хранилище кода;
- каким образом описывать commit, чтобы иметь понимание его влияния на проект;
- как фиксировать автоматически новый релиз проекта, а также иметь описание хронологии изменений кода в истории.
Pre-commit hooks
Для просмотра ссылки ВойдиВ случае, если вы пытаетесь произвести commit с сообщением(commit-message), не соответствующим стандарту (только если вы не внесли дополнительные изменения в файл конфигурации), инструмент сommitlint его блокирует. Теперь commit не может быть внесен на локальный репозиторий, либо на удаленный GitLab instance-сервер, что позволяет исключить человеческий фактор некорректного заполнения commit-сообщений, структурное и полное написание которых зачастую игнорируются.
Напомню, что некорректное заполнение commit-сообщений может привести к сложностям для понимания и поддержки проекта не только другими разработчиками, но и автору проекта, ввиду того, что внесенные изменения со временем могут забываться.
Запускается инструмент commitlint как husky pre-commit hook, то есть локально на сервере, с которого автор хочет произвести отправку сommit-а на удаленный gitlab-сервер.
Структура составления сообщения в commit-е должна выглядеть следующим образом:
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
Так выглядит пример commit-сообщения в соответствии с конвенцией описания:
feat(model): Add new OCR model which shows better performance on validation set
Ниже представлена таблица с описанием того, какие типы (название <type> в конвенции выше) использовать в случае добавления нового commit-а:
Type
Description
feat
A new feature
fix
A bug fix
docs
Documentation only changes
style
Changes that do not affect the meaning of the code (white-space, formatting etc)
refactor
A code change that neither fixes a bug nor adds a feature
perf
A code change that improves performance
test
Adding missing tests or correcting existing tests
build
Changes that affect the build system or external dependencies
ci
Changes to our CI configuration files and scripts
chore
Other changes that don't modify src or test files
revert
Reverts a previous commit
Pre-commit hooks в действии
Теперь покажу на примере, каким образом срабатывают pre-commit hooks. Для этого создадим проект под названием semantic-versioning, в котором помимо ветки main будет создана дочерняя ветка с названием feature/add-new-file.
- Для примера добавил в эту ветку новый файл с названием test.txt:
- Попытаемся сделать commit-message, не проходящий по конвенции наименования типов, описанных ранее в таблице:
- Видно, что наш commit не проходит из-за несоответствия конвенции названия типа внутри commit-message. Вместо указанного типа manual_test внутри commit-сообщения необходимо указать один из следующих: [feat, fix, refactor, config, ci, perf, test, docs, chore].
- Теперь исправим название типа внутри сообщения на конвенциональные
- (manual_test -> feat)):
- Видим, что добавление нового commit-а прошло без ошибок.
- Сделаем git-push в соответствующую названию remote ветку на gitlab server:
