Как да напишем ефективно, полезно Git Commit съобщение

Съобщенията за ангажимент са кратки описания на всеки комит в система за контрол на версиите като Git. Когато извършвате промени във вашите файлове на проекта, трябва да предоставите съобщение, обясняващо какво правят или защо сте ги направили.

Съобщенията за ангажиране служат като форма на документация и комуникация. Те играят решаваща роля в поддържането на ясна и организирана история на версиите на проекта. Научете как да пишете добри съобщения за ангажиране и другите членове на вашия екип ще оценят работата ви още повече.

Структура на добро съобщение за ангажиране

Един добър пример за съобщение за ангажиране включва четири раздела: Тип, Описание, Основен текст и Долен колонтитул.

Така:

: 
[тяло по избор]
[долен колонтитул по избор]

Тип

Типът описва вида на промяната, направена в настоящия комит. Можете да използвате всяка система, която е разумна за вашите обстоятелства. Например, ето някои примерни ключови думи, които можете да използвате, за да сигнализирате за всеки тип промяна, заедно с примерна употреба:

• подвиг: вашите промени въвеждат нова функция.
• поправя: коригирате грешка.
• рефактор: вашата промяна рефакторира кода, без да поправя грешка или да добавя нова функция.
• тест: правите промени, свързани с тестване. Например, когато вие пишете тестове с Jest или всякакви друга рамка за тестване ти избираш.
• скучна работа: промени, които не са свързани с корекция, функция или тест. Например, актуализиране на зависимости.
• документи: когато актуализирате документация.
• стил: промени, които не засягат значението на кода, като добавяне на бяло пространство, липсващи точки и запетая и др.
• перф: промени, свързани с подобрения в производителността.
• изграждане: когато правите промени, които засягат компилационните файлове.
• ci: промени, свързани с непрекъсната интеграция.
• връщане: при връщане към предишен ангажимент.

Описание

„Описанието“ на съобщение за ангажимент е кратко и описателно резюме на промените, направени в комита. Той служи като заглавие, което улавя същността на ангажимента.

Когато пишете описанието, имайте предвид следното:

• Направете го ясно и достатъчно конкретно, за да опишете ангажимента с един поглед.
• Направете го кратко и стегнато. В идеалния случай ограничаването му до 50 знака или по-малко би било най-добре.
• Напишете го в сегашно време, дори ако описвате вече направени промени.
• Използвайте повелителното наклонение, докато го пишете.
• Започнете го с главна буква.
• Не го завършвайте с период.

Например:

подвиг: Внедрете превключване на тъмен режим за начална страница

Този пример показва как можете да напишете описанието за ангажимент, който прилага тъмен режим. Той използва подвиг тип, защото въвежда нова функция.

Тяло (по избор)

Основният раздел на съобщението за ангажиране предоставя допълнителни подробности и контекст за промените, направени в ангажимента. Не винаги ще имате нужда от тяло, но то може да ви помогне да предоставите повече информация, да обясни мотивите за промяната или да опише всякакви технически съображения.

Ето някои неща, които трябва да имате предвид, докато пишете основния раздел на съобщение за ангажиране:

• Git никога не обвива текста автоматично, така че ръчно го обвивайте на 72 знака, когато пишете тялото. Това дава на Git достатъчно място за отстъп на текста, което го прави по-четлив.
• Използвайте тялото, за да обясните какво се е случило с промяната, защо сте направили промяната и мотивите зад вашата промяна.
• Трябва да оставите празен ред между описателния ред и основния текст. Това позволява на Git да прави разлика между тях.
• Ако ангажиментът въвежда множество промени или засяга различни области от кодовата база, обмислете използването на точки или абзаци, за да разбиете модификациите. Това подобрява четливостта и помага на читателите да разберат различните аспекти на ангажимента.

Например:

feat: Добавете GitHub като OAuth доставчик
Интегрирайте GitHub като доставчик на OAuth, за да активирате безпроблемно 
удостоверяване с GitHub акаунти.
- Прилагане на поток за удостоверяване на OAuth с GitHub API
- Конфигурирайте необходимите крайни точки и настройки за GitHub удостоверяване
- Актуализирайте потребителския интерфейс, за да включите опция за влизане в GitHub

Примерът по-горе показва добро съобщение за ангажиране на Git за функция, която добавя GitHub като OAuth доставчик към вашето приложение. Това съобщение за ангажиране има кратък обобщен ред (50 знака или по-малко), по-подробен обяснителен текст (обвит до около 72 знака) и точки за допълнителна информация.

Разделът на долния колонтитул в съобщението за ангажиране е незадължителна част, която предоставя допълнителна информация или метаданни, свързани с ангажирането. Обикновено се поставя след секцията на тялото, разделена с празен ред. Долният колонтитул може да включва различни видове информация, като препратки към свързани проблеми, тагове или специални бележки.

Когато препращате към проблеми, заявки за изтегляне или други свързани елементи, използвайте подходящия синтаксис или формат, изискван от системата за проследяване на проблеми на вашия проект. Това гарантира, че препратките са правилно разпознати и свързани.

Например:

feat: Добавете GitHub като OAuth доставчик
Интегрирайте GitHub като доставчик на OAuth, за да активирате безпроблемно 
удостоверяване с GitHub акаунти.
- Прилагане на поток за удостоверяване на OAuth с GitHub API
- Конфигурирайте необходимите крайни точки и настройки за GitHub удостоверяване
- Актуализирайте потребителския интерфейс, за да включите опция за влизане в GitHub
Решава: #123
Вижте също: #456, #789

Долният колонтитул препраща към свързания проблем #123 и споменава други свързани проблеми #456 и #789 за допълнителен контекст.

Добавяне на съобщението за ангажиране

Можете да пишете съобщения за ангажиране, като използвате -м флаг, последван от съобщението за ангажиране, оградено в кавички (незадължително, но препоръчително).

The -м флагът е идеален за кратки съобщения за ангажиране, обикновено включващи типа и описанието.

Например:

git commit -m "chore: Промяна на linter към ESlint"

Въпреки това, когато вашето съобщение за ангажимент изисква повече подробности, като например тяло и долен колонтитул, би било по-добре да напишете ангажимента в текстов редактор или IDE.

Като алтернатива можете да пишете дълги съобщения за ангажиране в текстов файл и да използвате --файл флаг за указване на съобщенията за ангажиране като съдържание на текстовия файл.

Например:

git commit --file commit_message.txt

Когато изпълните командата по-горе, git ще използва съдържанието на файла като съобщение за ангажимент.

Можете също да кажете на git да отвори вашия редактор по подразбиране, за да напише по-дълго съобщение. Ако сте задали променливата на средата GIT_EDITOR или EDITOR, git ще отвори тази програма, когато стартирате гол git ангажимент команда.

Защо трябва да пишете добри съобщения за ангажиране

Писането на добри съобщения за ангажиране е от решаващо значение за ефективното сътрудничество и поддръжката на кода. Ясните и описателни съобщения помагат за разбирането, отстраняването на грешки и прегледите на кода. Те дори могат да допринесат за проектна документация или бележки за изданието.

Те позволяват споделяне на знания, плавно включване и поддържат контрол на версиите. Приоритизирането на качествените съобщения за ангажимент подобрява процесите на разработка и гарантира поддръжка на кодовата база.