skip to content
QA Band Logo

Порядок має бути навіть у commit messages

/ 5 хв читання

Переглянути більше блогів з тегом  git • Переглянути більше блогів з тегом  commit
Порядок має бути навіть у commit messages
Зміст

Найпопулярнішим стандартом з оформлення комітів є - Conventional Commits.

Conventional Commits - це проста угода про те, як потрібно писати повідомлення commit’ів. Вона описує простий набір правил для створення зрозумілої історії commit’ів, а також дозволяє простіше розробляти інструменти автоматизації, засновані на історії commit’ів.

З цієї конвенції народилися інструменти commitizen і commitlint, які суттєво допоможуть зробити коміти «чистими» і «правильними»

Багато хто навіть не замислюється про коректні повідомлення при комітах, чи не так? Ось кілька добротних меседжів, які можна знайти на Github’i:

Глибокий аналіз дозволяє зрозуміти, що слово «shit» дуже популярне і без нього не має існувати такого поняття, як commit message 🤭

Якщо говорити серйозно, то дуже велику роль мають повідомлення, які ви залишаєте при коміті, і те, як ви вмієте грамотно та коректно описувати, що увійшло до вашого коміту - дорогого варте. Просто погляньте на лог комітів на вашому проекті і переконайтеся, що тих, хто пише коректні повідомлення, не так вже й багато.

Рекомендації щодо повідомлень коміту

«Правильні» повідомлення при комітах важливі, оскільки:

  • показують, що ви вмієте працювати в команді
  • допоможуть відтворити контекст для шматка коду
  • ви зможете з більшою ймовірністю знайти проблему в комітах, які були раніше

Кожна мова програмування має свій стайлгайд, якісь особливості форматування та іменування - це все допомагає уникнути проблем і хаосу. Подібний підхід потрібно використовувати і при комітах. Є безліч варіацій і гайдів по комітам, але пропоную виділити основні вже загальноприйняті положення.

  • Відокремлюйте заголовок від тіла повідомлення порожнім рядком.
  • Повідомлення коміту не повинно містити жодних помилок пробілів.
  • Прибирайте знаки пунктуації, в яких немає необхідності.
  • Не ставте крапку в кінці заголовка.
  • Заголовок і кожен окремий абзац мають починатися з великої літери.
  • У заголовку повідомлення використовуйте наказовий спосіб (рекомендовано самим Git).
  • Використовуйте тіло повідомлення, щоб описати внесені зміни і причини цих змін (до 72 символів).
  • Не припускайте, що рецензент знає про проблему, яку ви вирішуєте: обговорюйте її.
  • Дотримуйтесь угод про повідомлення комітів, прийнятих у вашій команді.

Рекомендується також вказувати тип коміту:

  • feat: нова фіча, яка додається до застосунку.
  • fix: виправлення бага.
  • style: функції та оновлення, що мають відношення до стилізації.
  • refactor: рефакторинг певної ділянки кодової бази.
  • test: все, що стосується тестування.
  • docs: все, що стосується документації.
  • chore: звичайна підтримка коду, рутина.

Ось відмінний шаблон хорошого повідомлення коміту, написаний Tim pope:

Capitalized, short (50 chars or less) summary


More detailed explanatory text, if necessary.  Wrap it to about 72
characters or so.  In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body.  The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.


Write your commit message in the imperative: «Fix bug» and not «Fixed bug»
or «Fixes bug.»  This convention matches up with commit messages generated
by commands like git merge and git revert.


Further paragraphs come after blank lines.


- Bullet points are okay, too


- Typically a hyphen or asterisk is used for the bullet, followed by a
  single space, with blank lines in between, but conventions vary here


- Use a hanging indent


If you use an issue tracker, add a reference(s) to them at the bottom,
like so:


Resolves: #123

Він же українською:

Повідомлення-заголовок. Коротке, до 50 символів. Починати з великої літери


Більш детальний пояснювальний текст (якщо потрібен). Має вміщатися в 72 символи. У деяких ситуаціях перший рядок повідомлення коміту (заголовок) сприймається як тема email-а, а решта тексту — як «тіло». Порожній рядок між темою і тілом має велике значення (за винятком випадків, коли у вас взагалі немає тіла повідомлення). Якщо заголовок і тіло повідомлення будуть йти підряд, без розділення порожнім рядком, це може збити з пантелику такі інструменти як rebase.


Дієслова в повідомленні коміту слід писати в наказовому способі: «Fix bug» («Виправ баг»), а не «Fixed bug» («Виправлений баг») або «Fixes bug» («Виправляє баг»). Коли повідомлення комітів генеруються командами git merge та git revert, вони пишуться саме в наказовому способі.


Абзаци відділяються один від одного порожніми рядками.


- Допускаються позначення пунктів списку.


- Зазвичай для пунктів списку використовуються знаки дефіса або зірочки з пробілом після них. Кожен пункт відділяється порожнім рядком, але це варіативно.


- Допускається зворотний абзацний відступ.


Якщо ви використовуєте issue tracker, додайте посилання(я) внизу, ось так:


Resolves: #123

Conventional Commits

Найпопулярнішим стандартом з оформлення комітів є Conventional Commits.

Conventional Commits - це проста угода про те, як потрібно писати повідомлення commit’ів. Вона описує простий набір правил для створення зрозумілої історії комітів, а також дозволяє простіше розробляти інструменти автоматизації, засновані на історії commit’ів.

З цієї конвенції народилися інструменти commitizen та commitlint, які суттєво допоможуть зробити коміти «чистими» та «правильними».

Приклад Conventional Commits:

fix: correct minor typos in code
see the issue for details on the typos fixed
closes issue #12

Корисні посилання

Обговорення
Вхід через GitHub
Завантаження коментарів...
Зміст