Як писати ефективні повідомлення Git Commit
Практичний посібник англійською мовою щодо написання чітких, професійних повідомлень верифікації Git — правила, приклади і поширені помилки, яких слід уникати.
Повідомлення про перенесення Git є однією з найчастіше написаних, але найменш обдуманих форм технічної англійської мови. Добре написане повідомлення про перенесення розказує історію вашої бази коду. Погано написаний — « fix stuff », « WIP », « asdfgh » — створює історію, яка є непотрібною для вашої команди і вашого майбутнього « я ».
У цьому підручнику описано правила, словниковий запас і особливі варіанти вибору мови, які роблять повідомлення про перенесення справді корисними.
Звичайний формат затвердження
Найпоширенішим стандартом є Conventional Commits, у якому використовується структурований префікс:
<type>(<scope>): <short description>
[optional body]
[optional footer]** Приклад: **
feat(auth): add JWT refresh token endpoint
Implements a /auth/refresh endpoint that accepts a valid refresh token
and returns a new access token. Refresh tokens expire after 7 days.
Closes #142Типи вказівок і коли їх використовувати
| Type | Use when | Example |
|---|---|---|
feat | Adding a new feature | feat(search): add full-text search to products |
fix | Fixing a bug | fix(api): handle null response from payment gateway |
docs | Documentation only | docs(readme): update local setup instructions |
style | Formatting, no logic change | style(button): apply consistent border-radius |
refactor | Code restructure, no feature or fix | refactor(user): extract validation into separate module |
test | Adding or updating tests | test(cart): add edge case for empty cart checkout |
chore | Maintenance tasks | chore(deps): upgrade eslint to v9 |
perf | Performance improvement | perf(query): add index to reduce user lookup latency |
ci | CI/CD configuration | ci(github): add step to run integration tests |
revert | Reverting a previous commit | revert: feat(auth): add JWT refresh token endpoint |
Введення рядка теми
Рядок теми (перший рядок) є найважливішою частиною повідомлення. Правила:
- ** Використовуйте наголос на першому складі: ** « Додати функцію », а не « Додати функцію » або « Додати функцію »
- ** Не більше 72 символів **
- Не закінчуйте пунктуацією
- ** Перше слово після префікса типу записується з прописною літерою **
** Приклади імперативних настроїв:**
| Wrong | Right |
|---|---|
| ”Fixed the login bug" | "fix(auth): resolve login failure on empty password" |
| "I added tests" | "test(user): add unit tests for email validation" |
| "Changes to config" | "chore(config): move timeout settings to env variables" |
| "Updated README" | "docs(readme): add Docker setup instructions” |
Імперативний настрій нагадує завершення речення: * « Цей запит буде… [додати кінцеву точку для оновлення токенів] » *.
Писання тіла
Тіло не обов’ язкове, але цінне для неочевидних змін. Використовуйте його, щоб пояснити:
-
- Чому * було внесено зміну (а не лише * що * змінено — це буде видно у порівнянні)
- Проблема, яка існувала раніше
- Компромиси или решения
** Приклади гарного тіла: **
- “Попередньо, всі з’ єднання з базою даних створювалися за запитом. Це призвело до виснаження резерву з’ єднань під час високої навантаження. Цей запит реалізує об’єднання з’єднань через pg-pool, обмежуючи з’єднання до 20 на один екземпляр.”*
- “У попередній реалізації використовувалося синхронне читання файлів, яке блокувало цикл подій під час великих вивантажень. Переключення на асинхронний поток API вирішує проблему продуктивності, повідомлену в #234.”*
** Що не можна вводити в організм: **
- Повторення того, що вже показано у diff
- Неясні висловлювання типу “внесли деякі покращення”
- Особисті зауваження («не впевнений, що це правильний підхід»)
Посилання на проблеми і запити на витягування
Більшість команд використовують ключові слова, які автоматично закривають проблеми під час об’ єднання перенесення:
Closes #142— закриває проблемуFixes #89— закриває проблему (також означає, що це була помилка)Refs #201— посилання без закінченняSee also #98— додатковий контекст
Поширені помилки повідомлень передачі
| Mistake | Why it’s a problem | Fix |
|---|---|---|
| ”fix” | Tells you nothing | ”fix(api): return 404 when user not found" |
| "WIP” | Not a complete thought | Squash WIP commits before merging |
| ”fixed a bug” | Past tense, vague | ”fix(checkout): prevent duplicate order submission" |
| "Updating stuff” | Completely meaningless | ”chore(deps): upgrade React to 18.3” |
| Very long subject | Hard to read in git log | Keep under 72 characters |
Корисні дієслова для повідомлень перенесення
Технічне записування звітів використовує певний набір дієслів, які послідовно виконуються:
** додавати **, ** вилучати **, ** оновлювати **, ** виправляти **, ** перебудовувати **, ** видобувати **, ** пересувати **, ** перейменовувати **, ** замінювати **, ** реалізовувати **, ** вводити **, ** виводити з ладу **, ** повертати **, ** вимкнути **, ** вмикати **, ** налаштовувати **, ** документ **, ** оптимізувати **
Чиста історія перенесення не є косметичною. Це те, що дозволяє вашій команді git blame, git bisect, і зрозуміти еволюцію кодової бази роками пізніше. Написати повідомлення для інженера, який прочитає їх о 23:00 під час інциденту — тим інженером можете бути ви.
Науковий ступінь кандидата наук: спеціалізація — «Професійна діагностика»
Написання ефективних повідомлень про верифікацію Git не просто про те, що ви змінили; це про те, щоб повідомити чому і як. Для не-рідних носіїв англійської мови, це може бути особливо складним завданням, тому що технічна мова часто має тонкі нюанси, які не відразу очевидні. Розглянемо деякі типові сценарії і як підійти до них з більшою точністю.
Одна з найчастіших проблем виникає під час перегляду коду. Уявіть, що ви отримали коментар на зразок « Цей запис не пояснює зміну ». Хоча це технічно вірно, але це не зовсім чітко і не дуже корисно. Краще було б відповісти: «Чи можете ви розібратися в обґрунтуванні цього рефакторингу? Зокрема, я б був вдячний за розуміння того, як він вирішує потенційне в’язке місце продуктивності, яке ми обговорювали на нашій останній зустрічі. “Зауважте зміну - він вимагає * роз’яснення *, а не просто критикує відсутність пояснень. Використання таких фраз, як «розробка», «розуміння» і «адресування» демонструє більш складне розуміння мети розмови. Це про те, щоб показати, що ви розумієте ширший контекст, а не тільки негайну зміну коду.
Інша ситуація може стосуватися створення опису запиту на звантаження. Припустимо, що ви додаєте нову функціональність — ви можете написати щось на зразок « Додано нову функціональність ». Цей запис буде надзвичайно коротким і не надасть жодної цінності для рецензентів. Замість цього, намагайтеся вказати щось більш описове: « Реалізовано автентифікацію користувача за допомогою OAuth 2. 0, дотримуючись правил безпеки, описаних у документі [посилання]. Це розширення дозволяє користувачам реєструватися через їх існуючі облікові записи Google, спрощуючи процес реєстрації. Ключовим тут є впровадження конкретної термінології - “OAuth 2.0”, “рекомендації з безпеки” - і чітке зазначення впливу зміни (“оптимизація процесу реєстрації”). Використання активного голосу («Вреалізовано…») також покращує ясність у порівнянні з пасивними конструкціями.
Нарешті, розгляньте розмови Slack навколо повідомлень про затвердження. Колега може сказати: « Я тільки- но зробив швидке виправлення ». Цей вираз часто використовується у неформальному контексті, але у професійному контексті він може ввести у оману. Краще повідомити: «Розв’язана проблема #123 — перервна помилка, що спричинила пошкодження даних, була відстежена і виправлена за допомогою стратегії відновлення. Я додав докладні коментарі у звіті, пояснюючи процес зневадження. “Знову ж таки, бути конкретним - посилання на номер проблеми, детально описуючи « стратегію відновлення » і пояснюючи « процес зневадження » - значно покращує розуміння і полегшує співпрацю. Пам’ ятайте, короткий не завжди рівно ефективний; точність і контекст є найважливішими.