Правила написання commit повідомлень
02 Nov 2023
В даній статі буде зібрана вся інформація та написані правила ведення версіонування для проєктів, де це потрібно.
Як створювати правильні commit повідомлення?
Почнемо з правил формування commit повідомлення, як базу ми будемо використовувати напрацювання команди розробників AngularJS, які використовують логіку "Conventional Commits":
Кожен розробник, який працює на проєкті повинен дотримуватись даних правил.
Сьогодні ми навчимось писати такі повідомлення, до яких не страшно буде повертатись через великий проміжок часу, додатково навчимось їх структурувати по тематиці, що в майбутньому дасть можливість у ведені версій проєкту і так званих списку змін "Changelog".
Як повинен виглядати commit message?
Кожне повідомлення про зафіксовану зміну складається з заголовка (header), тіла (body) та нижньої частини (footer). Заголовок має спеціальний формат і включає тип (type), область (scope) та предмет (subject):
Скелет commit повідомлення:
<type>(<scope>): <subject>
<body>
<footer>Після заголовка є порожній рядок, далі йде тіло та ще один порожній рядок, і, нарешті, нижня частина.
Заголовок (1 рядок) обов'язковий, а header та footer є необов'язковою.
Жодний рядок повідомлення не може бути довшим 100 символів! Це дозволяє зробити повідомлення легшими для читання на GitLab та в різних git-інструментах.
Що робити при Revert-і?
Якщо зафіксована зміна скасовує попередню зміну, вона повинна починатися з type = "revert:", за яким слідує заголовок скасованого зафіксованого змінного повідомлення. В нижній частині повідомлення повинно бути написано: Це скасовує зафіксовану зміну <хеш>, де <хеш> - це SHA зафіксованого змінного повідомлення.
Приклад такого revert commit-у:
revert: let us never again speak of the noodle incident
Refs: 676104e, a215868Давайте розберемось в типах (Type) детальніше:
Типи допомагають групувати commit-и по їх логічному предназначенню, давайте розберемось який тип потрібно використовувати для певної задачі:
feat:(скорочення від feature) - Нова функція, імплементація нового функціоналуfix:Виправлення помилок, правкиlayout:Зміни в розмітці, додавання нових сторінокdocs:Зміни в документаціїstyle:Зміни, які не впливають на зміст коду та його функціонал (пропуски, форматування, відсутні крапки з комою тощо)refactor:Зміни в коді, які не виправляють помилки та не додають нового функціоналу, проте покращують його читабельністьperf:(скорочення від performance) - Зміни в коді, які покращують продуктивністьtest:Додавання відсутніх тестівchore:Зміни в процесі зборки або допоміжних інструментах та бібліотеках, таких як генерація документації. Узагальнюючи, тип "chore" використовується для комітів, які стосуються побічних аспектів проекту, таких як оновлення інфраструктури, документації, чистки коду, завдань збирання та інших справ, які покращують процес розробки та супроводу, але не впливають на конкретні функції програми.
Тепер розглянемо область (Scope), що це і як з цим працювати:
Область може бути чим завгодно, що вказує на місце зміни зафіксованої зміни. Наприклад, $location, $browser, $compile, $rootScope, ngHref, ngClick, ngView тощо...
Це поле є необов'язковим і повинно тримати логічну сферу що саме ви правили, в більшості випадків вам цього не потрібно буде на класичних BOLD проєктах, проте спробую навести приклади використання для фронтів та беків:
Для фронтів: Ви додали нову анімацію на сторінку, тоді ваш commit message буде виглядати приблизно так:
feat(animation): add AOS animation on "About Us" Page
Для беків: Ви додали можливість реєстрації та логіну на проєкт через Google API, тоді ваш commit message буде виглядати приблизно так:
feat(auth): add ability to login via Google APIТепер поговоримо про предмет (Subject):
Subject - це по суті короткий опис того, що ви робили в даному commit-і. Головне що потрібно розуміти, це те, що в такому варіанті ведення commit повідомлень потрібно часто комітити, а не зберігати все в 1 кучу, оскільки так важче буде сформувати коротке повідомлення, підібрати правильний тип та додати опис. Тому не бійтесь зберігати свої зміни багато разів, це полегшить вашу роботу в рази.
- Використовуйте імператив, теперішній час: "add" а не "added" чи "adds".
- Не починайте з великої літери.
- Не ставте крапку (.) в кінці.
Тепер поговоримо про тіло повідомлення (Body):
Так само, як у заголовку, використовуйте імператив, теперішній час: "change" а не "changed" чи "changes". Тіло повинно містити мотивацію для зміни та порівнювати її з попередньою поведінкою. Тут ви повинні при потребі більш детально описати що саме було зроблено і як змінено, дане повідомлення буде видиме тільки при повному відкритті коміту.
Ну і нижня частина (Footer) на кінець:
Нижня частина повинна містити інформацію про руйнівні зміни (BREAKING-CHANGE) та також місце для посилання на GitLab-питання (issue), які закриває ця зафіксована зміна.
Руйнівні зміни повинні починатися зі слова "BREAKING CHANGE:", з пробілом або двома новими рядками. Залишок повідомлення зафіксованої зміни використовується для цього.
Опис, який ви щойно прочитали використовується для стандартизування посилань на проблеми, які цей коміт вирішує, додатково можуть бути записані ВАЖЛИВІ ЗМІНИ, які можуть ламати API коли його проектують.
Для випадків наших проєктів тут буде посилання на лістинг, який покриває даний коміт, або таск)
Приклад сформованого commit-у внизу:
feat(animation): add AOS animation for better UX experience
Add AOS.js library to project dependencies, use it on every page inside project.
Refs: bold:1q6:25В прикладі зверху вказано що таск знаходиться в нашому менеджері, Workspace BOLD, посилання на <хеш> лісту - 1q6, номер таску в тому лісті - 25.
Для використання множинного посилання варто використовувати логіку масивів, приклади внизу, де ми використали для номерів завдань написання, яке пояснюється як, від 24 по 29 (це все включно), та ще додатково 32, який не входить в даний діапазон. Також варто їх писати у зростаючому кейсі, аби було легше їх шукати.
Додатково, якщо 1 коміт фіксить декілька тасків з різних лістів, тоді варто писати 2 різними посиланнями, глобально через кому (на прикладі винесено внизу)
Refs: bold:1q6:[24-29,32]
Refs: bold:1q6:32, bold:ed2:12Bonus:
Для легкості ведення даних правил пропоную встановити плагін для WebStorm, PHPStorm, який буде сам підказувати вам загальні моменти та перевіряти стилістику вашого повідомлення: link
Plugin for WebStorm, PHPStorm
Також раджу використовувати AI Assistant JetBrains, який вміє сам формувати commit message дивлячись за файлами які ви додали в stage, тоді вам треба буде тільки трошки підправити його аби він відповідав усім новим стандартам
Image
References:
Посилання на "Політику коміт повідомлень": link
Також цікава стаття про політику комітів на базі AngularJS: link
Плагін Intellij для формування комітів через AI: link
