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

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

Для людей, для яких англійська мова не є рідною, повідомлення про затвердження представляють особливий виклик: вони повинні бути короткими (ідеально, не більше 72 символів у рядку теми), семантично точними і написаними у певному граматичному стилі, який не збігається з повсякденною мовою.

Цей посібник містить розширені шаблони: специфікацію звичайних підписань, семантичний словник змін, проблеми з посиланнями, а також правила написання англійською мовою, які відрізняють хорошу історію git від виняткової.

Граматика, яка дивує всіх

Універсальним правилом у повідомленнях про перенесення англійською мовою є написання ** імперативного настрою ** — форми дієслова, яка звучить як команда:

• ** Правильно: ** Fix the race condition in the session handler
• Неправильно: Fixed the race condition (минулий час)
• Неправильно: Fixing the race condition (заокруглено)
• Неправильно: This fixes the race condition (декларативне)

** Чому імператив? ** Тому що git revert генерує повідомлення, як Revert "Add feature X". Рядок теми перенесення повинен завершуватись реченням: * « Якщо застосувати, цей перенесення буде… » *

• “Якщо застосувати, цей звіт Видалити умову переслідування в обробнику сеансів.”
• “Якщо застосувати, цей звіт додасть Додати підтримку потоку пристроїв OAuth 2.0.”

Це граматичний контракт формату повідомлення про перенесення.

Специфікація звичайних запитів

Звичайні затвердження — це специфікація, яка додає ** структурований семантичне значення ** до повідомлень затвердження. Це є основою для автоматизованих changelogs, семантично версійного управління, і CI / CD конвеєрів, які аналізують історію затверджень.

Основний формат

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Типи і їх значення

Кожен тип має певне семантичне значення:

Type	Meaning	CHANGELOG section
feat	A new feature visible to users	Features
fix	A bug fix	Bug Fixes
docs	Documentation changes only	—
style	Formatting, whitespace — no logic change	—
refactor	Code restructuring — no feature or fix	—
perf	Performance improvement	Performance
test	Adding or updating tests	—
build	Build system or dependency changes	—
ci	CI configuration changes	—
chore	Maintenance tasks	—
revert	Reverting a previous commit	—

Зміни в графіку

Знак ! після типу (або BREAKING CHANGE: у нижньому колонтитулі) означає, що цей звіт вводить несумісну зміну API — він перевершує ** головну ** версію у семантичній версії:

feat!: Remove deprecated v1 authentication endpoints

BREAKING CHANGE: The /api/v1/auth/* endpoints have been removed.
Consumers must migrate to /api/v2/auth/* before upgrading.
See migration guide: https://docs.example.com/migration/v1-to-v2

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

Рядок теми є найчастіше читається частиною повідомлення про оприлюднення. Правила:

• ** 50- 72 символи** максимум (72 — це жорстке обмеження, яке застосовується більшістю інструментів)
• ** Нижній регістр ** після префікса типу (крім власних іменників)
• ** Без крапки ** в кінці
• ** Будь конкретним ** — « Виправити помилку » є непотрібним; « Виправити нульовий вказівник у вилученні елемента кошика » є корисним

Специфічні приклади

Vague	Specific
fix: Fix bug	fix: Prevent null pointer when cart is empty at checkout
feat: Add feature	feat(auth): Add TOTP-based two-factor authentication
refactor: Refactor code	refactor(parser): Extract token validation into standalone module
chore: Update deps	chore: Upgrade PostgreSQL driver from 14.2 to 15.0
docs: Update readme	docs: Add environment variable reference to deployment guide

Використання Scope

Необов’ язковий обсяг у дужках визначає підсистему або модуль, на який буде вплинено:

feat(api): Add pagination to /users endpoint
fix(auth): Correct token expiry calculation for UTC offsets
perf(search): Cache Elasticsearch query results for 60 seconds

Область застосування є командними угодами — погоджуються на послідовному списку (наприклад, api, auth, ui, db, ci ) і дотримуються його.

Запис тіла перенесення

Тіло не обов’ язкове для простих змін, але обов’ язкове для:

• Неочевидних рішень
• Виправлення помилок, якщо основна причина не очевидна
• Переломні зміни
• Все, что может сбить с толку следующего читателя

Правила написання тіла

• Відокремте від теми ** порожнім рядком **
• Переносити рядки на ** 72 символи ** на рядок (більшість редакторів можуть зробити це автоматично)
• Поясніть ** чому **, а не ** що ** — diff показує, що змінилося; тіло пояснює обґрунтування
• Використовуйте повні речення з прописними літерами і пунктуацією
• Для описів пишіть у теперішньому часі, але для контексту можна використовувати минулий час

Приклади тіл

** Хорошее тело - поясняет рассуждение: **

fix(cache): Use write-through strategy for session data

Previously, sessions were cached with a write-back strategy, which
created a window where a server restart could lose session data
before it was persisted. This was acceptable in development but
caused intermittent logouts in production during rolling deploys.

Write-through adds a small latency cost (~2ms per write) but
eliminates the data loss risk entirely.

** Добрий текст — пояснює обмеження: **

feat(export): Limit CSV export to 100,000 rows

The previous implementation had no row limit, which allowed users
to trigger exports that consumed all available memory on the export
worker. We've added a hard limit of 100,000 rows with a clear
error message directing users to the API for larger datasets.

This is a temporary measure while we implement streaming exports
in the next sprint. See JIRA-4821.

Посилання на джерела та цитати

Посилання на випуск у нижньому колонтитулі

Нижній розділ використовується для метаданих — посилань на проблеми, співавторів і поміток щодо змін:

Closes #342
Fixes JIRA-1234
Refs #298, #301
Reviewed-by: Alice Chen <alice@example.com>
Co-authored-by: Bob Smith <bob@example.com>

** Конвенції щодо ключових слів: **

• Closes #X або Fixes #X — автоматично закриває проблему, коли PR зливається (GitHub/GitLab)
• Refs #X або Related to #X — зв’язки без закриття
• Part of #X — сигналізує, що це один затвердження в більшій можливості

Посилання на декілька сховищ

Коли перенесення стосується проблеми в іншому сховищі:

Fixes org/other-repo#45

Посилання на документацію та рішення

See ADR-027 for the rationale behind this approach.
Migration guide: https://docs.example.com/migrate/v3
Spec: https://www.rfc-editor.org/rfc/rfc7519 (JWT)

Відновити затвердження

Під час повернення Git створює:

Revert "feat(auth): Add TOTP-based two-factor authentication"

Додати текст, який пояснює * чому * ви повернули:

Revert "feat(auth): Add TOTP-based two-factor authentication"

Reverting due to a critical regression in the SMS fallback path.
When TOTP is enabled and the user has no recovery codes, the login
flow enters an unrecoverable state. Reverting to unblock release;
the fix will be tracked in AUTH-892.

Передавати повідомлення з анти- шаблонами, яких слід уникати

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

Anti-pattern	Problem	Better
WIP	No information	feat(auth): Implement TOTP setup flow (in progress)
fix: fixed	Duplicate and vague	fix(api): Return 404 instead of 500 for missing resources
changes	Noise	Describe the actual change
as per review comments	No substance	List what specifically changed
update	Almost meaningless	Specify what was updated and why
minor fix	Relative and vague	Describe the specific fix
temp	Never meant to be permanent	Address and commit properly

Практична англійська мова

** Використовуйте активний голос. ** Повідомлення про перенесення повинні бути активними, прямими і точними:

• 10000000000000000♠0,0000000000000000000♠0,000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
• 10000000000000000♠0,0000000000000000000♠0,000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000

** Віддавайте перевагу конкретним дієсловом. ** Замість « оновити » або « змінити » використовуйте дієслово, яке точно описує зміну:

• Add, Remove, Replace, Extract, Rename, Move, Fix, Correct, Prevent, Allow, Disable, Enable, Upgrade, Downgrade, Revert

** Одна зміна на затвердження. ** Це так само англійський принцип, як і принцип git. Якщо ваше повідомлення про оприлюднення потребує « і » для опису змін, розгляньте можливість розділити його на дві частини.

Ключеві моменти

• Використовуйте ** імперативний настрій **: « Виправте ваду », а не « Виправлено » або « Виправлення ».
• Conventional Commits додає структуроване семантичне значення: feat, fix, refactor, chore, та інші сигналізують рівень впливу та категорію CHANGELOG.
• Суфікс ! і нижній колонтитул BREAKING CHANGE: сигналізують про вибухи головної версії.
• ** Рядки теми ** повинні містити 50- 72 символи, бути конкретними і використовувати конкретні дієслова.
• ** Тіло ** пояснює * чому *, а не * що * — diff показує, що змінилося.
• ** Нижні колонтитули ** містять посилання на випуск ( Closes #X ), співавторів і пояснення змін.
• Уникайте анти-патернів: WIP, fix: fixed, update, changes — вони пошкоджують вашу історію git.

Історія git, яка добре зберігається, є живим документом. Напишіть його для інженера, якому він знадобиться о 23:00 під час інциденту — і цей інженер може бути вами.