Эта тема, кажется, не так важна, но она довольно практична в повседневном программировании. Как правильно написать сообщение git commit?

Ни один способ написания не является правильным или неправильным; однако, если у каждого человека в проекте свой стиль сообщения коммита, то когда мы смотрим историю коммита,как что-нибудь понять? Не говоря уже о том, когда нам нужно искать и проверять коммиты...

Так есть ли какие-то правила, которые являются общими для всех и могут быть общими для многих проектов? 

Обычные коммиты

Обычные коммиты - это набор правил написания сообщений которые легко читаются как машинами, так и людьми. Машины могут использовать эти правила, например, в инструментах для автоматического управления версиями.

Этот набор правил соответствует SemVer (семантической версии) по способу описания функций, исправлений ошибок, рефакторинга кода или критических изменений, внесенных в сообщения фиксации. В настоящее время этот набор правил обычных коммитов находится в версии 1.0.0-бета.4 , и в будущем могут быть дополнения. 

Вы можете сослаться на реализацию обычных коммитов в некоторых открытых проектах на Github, некоторые из более крупных - это  Electron , IstanbulJs , Yargs и Karma,  , которые, если я правильно понял, фактически заложили основы для семантических коммитов.

Сообщение должно быть структурировано следующим образом:

<type>[optional scope]: <description>

[optional body]

[optional footer]

Где:

1. Символ type и description требуется для сообщения о коммите, а все остальные являются необязательными.
2. type: ключевое слово для классификации, если коммит был функцией, исправление ошибки, рефакторинг ...
3. scope: используется для категоризации коммитов, но отвечает на вопрос: что это за рефакторинг коммитов? Он должен быть заключен в круглых скобках сразу после type, например feat(authentication):, fix(parser):.
4. description: краткое описание того, что было изменено в коммите.
5. body: более длинное и подробное описание, необходимое, когда описание не может занимать одну строку:

$ git commit -m "feat: allow the provided config object to extend other configs
BREAKING CHANGE: `extends` key in the config file is now used for extending other config files"

1. footer: некоторая дополнительная информация, такая как идентификатор запроса извлечения, участники, номера выпусков ...

Вот несколько примеров короткого сообщения о коммите:

# ex1: 
$ git commit -m "feat: implement AVOD content reels"
# ex2: 
$ git commit -am "fix: routing issue on the main page"
# ex3 with scope: 
$ git commit -m "fix(player): fix player initialization"

Семантическая версия

Обычный коммит совпадает с SemVer через type в сообщении коммита. Инструменты автоматического управления версиями также полагаются на него, чтобы выбрать новую версию для исходного кода. Со следующим соглашением:

1. fix: фиксация типа (ошибка) исправления равна PATCH в SemVer.
2. feat: функция фиксации типа равна MINOR в SemVer.
3. Кроме того, ключевое слово BREAKING CHANGE в body разделе сообщения коммита будет означать, что этот коммит имеет модификацию, которая делает код более не совместимым с предыдущей версией. Подобно изменению структуры ответа API, часть ответа дескриптора предыдущей структуры, конечно, больше не будет точной, и теперь нам нужно создать совершенно новую версию, увеличив версию MAJOR SemVer.

Некоторые общие type применения включают в себя:

1. feat: новая функция для пользователя, а не новая функция для скрипта сборки
2. fix: исправление ошибки для пользователя, а не исправление скриптов сборки
3. refactor: рефакторинг производственного кода
4. chore: обновление заданий и т.д .; без изменения производственного кода
5. docs: изменения в документации
6. style: форматирование, пропущенные точки с запятой и т.д .; без изменения кода
7. perf: код улучшен с точки зрения производительности обработки
8. vendor: обновить версию для зависимостей, пакетов.
9. test: добавление недостающих тестов, рефакторинг тестов; без изменения производственного кода

Хотя это наиболее распространенные типы, которые вы увидите в практике, ничто не мешает вам создавать свои собственные типы коммитов.

Например, ниже приведен годовой объем git коммитов в основной ветке:

$ cd /tmp/karma
$ git log --pretty=oneline --no-merges --since 2017/01/01 --until 2017/12/31 | cut -d " " -f 2 |\
cut -d "(" -f 1 | cut -d ":" -f 1 | sort -r | uniq -c | sort -nr -k1
     39 chore
     28 fix
     23 feat
     15 docs
      6 test
      2 Try
      1 refactor

Резюме

1. Сообщения коммита должны иметь префикс типа (существительное), такого как feat, fix и т.д., Сразу за ним следует область (если есть), двоеточие и пробел.

$ git commit -am "test: add missing tests for promo reels"

1. feat - этот тип требуется использовать при добавлении функции
2. fix  - этот тип требуется использовать при исправлении ошибки
3. Если есть область действия, она должна быть существительным, которое описывает область изменения кода и должна быть помещена сразу после типа. Например, feat (аутентификация). 

$ git commit -am "refactor(auth): improve refresh token logic"

1. Описание должно быть кратким описанием изменений в коммите и должно соответствовать типу с областью действия или без нее.
2. Длинный коммит может иметь тело сразу после описания, предоставляя контекст для изменений. Между описанием и текстом должна быть пустая строка.
3. Нижний колонтитул можно разместить сразу после тела, но между телом и нижним колонтитулом должна быть пустая строка. Нижние колонтитулы должны включать расширенную информацию о коммитах, таких как связанные запросы, рецензенты, критические изменения. Каждая информация в одной строке.
4. Другие типы, кроме feat и fix могут быть использованы в сообщениях фиксации.
5. Передача критических изменений должна быть указана в начале или в нижнем колонтитуле с помощью заглавного BREAKING CHANGE ключевого слова. Далее следуют двоеточие, пробел и описание. Например:

$ git commit -m "feat(OAuth): add scopes for OAuth apps  

BREAKING CHANGE: environment variables now take precedence over config files."

Восклицательный знак ! может быть добавлен перед type/scope чтобы привлечь внимание и подчеркнуть, что коммит содержит критические изменения.

Итак, теперь, после того, как проект использует стандартизированные коммиты, мы имеем:

1. Легко читаемую историю проекта
2. способ использования Semantic Release для автоматизации управления версиями и автоматического создания журналов изменений для проекта с помощью плагинов семантического выпуска.
3. способ использовать Commit Lint для фиксации сообщений в соответствии с обычными коммитами.
4. поиск, фильтрация и анализ истории коммитов также более просты, когда вы можете использовать инструменты регулярных выражений или git для фильтрации коммитов по type или scope(или обоим).

Несколько полезных ссылок

https://www.conventionalcommits.org/en/v1.0.0-beta.4/#specification
https://github.com/angular/angular/blob/master/CONTRIBUTING.md#commit
https://github.com / Traditional-changelog / commitlint / tree / master /% 40commitlint / config-Traditional
https://karma-runner.github.io/0.10/dev/git-commit-msg.html
https://electronjs.org/docs/ разработка / pull-запросы # commit-message-guide
https://chris.beams.io/posts/git-commit/#seven-rules
https://codito.in/semantic-commits-for-git