Повідомлення Git Commit: Best Practices and English Tips (англійською)

Історія ваших звітів — це журнал рішень, написаних англійською мовою. Кожен розробник у вашій команді — зараз і в майбутньому — буде читати його. Чиста історія перенесення — це документація. Нечистий - це шум.

Написання хороших повідомлень про верифікацію — це навички написання, а не лише навички роботи з Git. Ось все, що тобі потрібно, щоб зробити це добре.

---

Чому важливо мати спільні інтереси?

Неправильний журнал оприлюднення виглядає так:

fix
wip
asdf
changes
fixed the thing
updated
more work on login
final fix (for real this time)

Хороший журнал звітів говорить про дещо:

feat(auth): add JWT refresh token rotation
fix(api): return 422 instead of 500 on invalid email format  
docs(readme): document environment variable setup for local dev
refactor(cart): extract price calculation into a pure function
chore(deps): upgrade React from 18.2 to 18.3

Різниця не в рівні навичок — це звичка і практика.

---

Звичайний формат затверджень

** Звичайні перенесення ** є найпоширенішим стандартом форматування повідомлень про перенесення у професійних командах. Шаблон:

<type>(<scope>): <short description>

[optional body]

[optional footer: closes #123, breaking change note, etc.]

Найпоширеніші типи

Type	When to use it
feat	A new feature
fix	A bug fix
docs	Documentation changes only
style	Formatting, whitespace — not CSS styling
refactor	Code restructured without changing behaviour
test	Adding or fixing tests
chore	Maintenance: dependency updates, CI config, build scripts
perf	Performance improvement
revert	Reverting a previous commit

Область дії (необов’ язкове, але корисне)

Обсяг — це частина кодової бази, яка зазнала впливу: auth, api, ui, db, cart, payments, ci, readme …

fix(auth): handle expired tokens gracefully refactor(db): replace raw queries with ORM methods

---

Введення рядка теми

Рядок теми є найважливішою частиною повідомлення про перенесення змін. Вона з’являється в git log, списках запитів на витягування, та інструментах перегляду коду.

Правила для рядка теми

1. ** Використовуйте наголос на обов’ язковому положенні ** — пишіть так, ніби ви даєте команду 1080 рік 10000000000000000♠0,00000000000000000♠0,00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 10000000000000000♠0,00000000000000000♠0,00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000

2. ** Не перевищуйте 72 символів ** — довші заголовки буде обрізано у багатьох інструментах

3. ** Починається з типу, потім двокрапкою, потім описом ** feat(payments): add Stripe webhook handler

4. ** Описати що робить затвердження, а не як** 1080 рік 10000000000000000♠0,00000000000000000♠0,00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000

5. Не закінчуйте пунктуацією 10000000000000000♠0,00000000000000000♠0,00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 1080 рік

---

Імперативний настрій: чому це важливо

Імперативний настрій означає написання дієслова так, ніби видаєте інструкцію. Подумайте про це так: “Якщо застосувати, цей затвердження буде ___.”

• ✅ “Якщо застосувати, цей запит додасть додати автентифікацію JWT”
• ✅ “Якщо застосовано, цей запит виправить нульовий вказівник при вході”
• ✅ “Якщо застосовано, цей запит вилучає застарілі кінцеві точки API”

Імператив проти інших форм дієслова

❌ Wrong	✅ Correct (imperative)
added password validation	add password validation
fixing memory leak in cache	fix memory leak in cache
updated dependencies	update dependencies
new feature: dark mode	feat(ui): add dark mode toggle
changes to improve performance	perf(db): add index on user email column

---

Англійські слова для повідомлень про затвердження

Вам не потрібен великий словниковий запас. Ці дієслова охоплюють більшість ситуацій:

Verb	Use for
add	New feature, file, endpoint, test, dependency
fix	Bug fix
update	Modifying something that already exists
remove / delete	Removing code, files, endpoints
refactor	Restructuring code without changing behavior
rename	Renaming files, functions, variables
improve	Making something better (vague — try to be more specific)
extract	Moving code into a separate file or function
merge	Merging branches (usually auto-generated)
revert	Undoing a previous change
bump	Version number increase (common for chore/deps commits)
migrate	Moving data or code to a new format/location

---

Запис тіла перенесення (для складних змін)

Для простих змін достатньо буде ввести рядок теми. Для складних переробок, змін архітектури або неочевидних виправлень додайте тіло повідомлення.

Тіло відповідає: ** Чому була зроблена ця зміна? ** Не що — diff показує що. Тіло пояснює розум.

fix(auth): prevent session fixation on login

Previously, the session ID was not regenerated after successful 
authentication, making the app vulnerable to session fixation attacks.

This change calls `req.session.regenerate()` immediately after 
the user credentials are validated, before writing any data to the 
session.

Closes #487
Related to #423 (auth hardening sprint)

Корисні фрази для тіла перенесення

• “Працював раніше, цей код…” * — пояснює, що відбувалося раніше
• « Ця зміна… » * — пояснює, що ви змінили і чому
• « Це виправляє… » * / * « Це вирішує… » * — посилання на проблему
• « Зауваження: це зміна, яка призведе до зупинки — виклики мають бути оновлені… » * — прапорці впливу “Closes #123” / “Fixes #456” — посилання на проблему GitHub (автоматичне закриття при злитті)

---

Переписування поганих повідомлень про затвердження: практика

Спробуйте виправити їх перед тим, як прочитати виправлення:

** Погана: ** fix stuff in auth Краще: fix(auth): redirect to /login after session timeout

---

** Погана: ** wip ** Краще: ** feat(search): implement fuzzy search using fuse.js (in progress) — або, ще краще, скористайтеся гілкою і зніміть її перед злиття.

---

** Погана: ** updated the thing Краще: chore(ci): update Node.js version to 22 in GitHub Actions workflow

---

** Погана: ** changes for sarah Краще: refactor(reports): split CSV export into a background job per Sarah's review

---

«Відмінність» не має значення

Не всі звітування потребують формату звичайних звітувань. У сольному проекті, невеликій команді з іншими правилами або прототипі, строге форматування може бути занадто жорстким. Що завжди має значення:

1. ** Рядок теми повідомляє вам про те, що сталося без читання diff **
2. ** Ви не брехали ** — повідомлення описує, що насправді робить цей запит

Перше перенесення — те, яке починає новий проект — зазвичай виконується так:

initial commit

Без типу, без обсягу. Все это понимают.

---

Добрі повідомлення про перенесення — це професійний сигнал. Коли старший розробник читає вашу історію git і бачить чіткі, послідовні, інформаційні повідомлення, він довіряє вашій роботі, перш ніж прочитає жодний рядок коду.

Мова: англійська, рідна мова для кількох мовців

Написання ефективних повідомлень Git commit стосується більше, ніж просто опису * того, що * змінилося; це стосується чіткого та професійного спілкування всередині команди, часто через значні мовні бар’єри. Хоча розуміння формату конвенційних підписів — з використанням префіксів, таких як feat, fix, docs — є ключовим, освоєння тонких нюансів англійської фрази може значно поліпшити розуміння і зменшити непорозуміння. Багато розробників, які працюють в міжнародних командах, стикаються з вираженням технічних змін коротко, одночасно дотримуючись стандарту, який вимагає певного словника. Це неймовірно поширене явище, коли повідомлення про перенесення є надто короткими, залишаючи переглядачів з питанням, чому саме зміна була внесена, або навпаки, надто довгими, затьмарюючи основні наміри.

Розглянемо сценарій: Сара з Польщі працює над новою функцією в React. Вона пише повідомлення про затвердження, в якому просто зазначає «Видалити помилку». Хоча технічно це вірно, це не дає достатньо контексту для її колеги по команді, Девіда, який базується в Німеччині. Він одразу запитує, яка помилка була виправлена і які наслідки. Більш вишуканим підходом буде « виправити: розв’ язати проблему з неправильним обробленням даних під час надсилання форми ». Двійковий знак відокремлює тип перенесення від опису, що надає вам можливість негайно побачити, що саме відбувається. Зауважте використання слова « розв’ язати » — це трохи більш формальний і професійний термін, ніж просто « виправити ». Крім того, вказівка « неправильної обробки даних під час надсилання форми » надає набагато яснішу картину проблеми і її розв’ язання.

Інша часта проблема виникає при обговоренні змін або регресій. Просто сказати « Виправити пошкоджену функцію » недостатньо. Замість цього, розгляньте такі формулювання, як « рефактор: Регресія адреси, введена у v2. 7. x, пов’ язана з автентифікацією користувача ». Включення номера версії негайно підкреслює обсяг зміни і надає змогу для цілеспрямованого тестування. Не менш важливо уникати надмірно неформальної мови. Хоча ми цінуємо дружній тон, повідомлення про перенесення повинні зберігати професійну формальність. Фрази на кшталт « Виправлено!» або « Швидке виправлення » зазвичай не підходять для виробничих середовищ. Сфокусуйтеся на точності – описайте дійсність, яку ви здійснили, і її вплив.

Нарешті, пам’ ятайте, що повідомлення про затвердження призначені не тільки для переглядачів; вони є документацією вашої роботи. Спробуйте дотримуватися послідовності у вашій фразі впродовж всього проекту. Якщо ви використовуєте « розв’ язати » у одному випадку, тримайтеся його, якщо не існує переконливої причини для зміни. Створення спільного розуміння цих тонких лінгвістичних виборів значно поліпшить співпрацю і зменшить неоднозначність у вашій команді - в кінцевому підсумку призведе до гладких переглядів коду і менше витрачених годин на переслідування неясних намірів.