Англійською: Writing Changelogs and Communicating Changes

Introduction

Замітки про випуск і журнали змін є одними з найчастіше написаних — і найчастіше недооцінених — технічних документів. Вони повідомляють про зміни користувачам, клієнтам та іншим розробникам. Добре написані замітки про випуск будують довіру; погано написані створюють збої і навантаження на підтримку. Для людей, для яких англійська мова не є рідною, освоєння певного словникового запасу і шаблонів написання зауважень до випуску є особливо цінним, оскільки це надає вам змогу чітко і професійно повідомляти про зміни, незважаючи на мовні бар’ єри. Цей посібник містить словниковий запас, структуру та фрази, які роблять нотатки про випуск ефективними.

Формат журналу змін

Найпоширеніший формат журналу змін відповідає вимогам « Зберігати журнал змін », у якому визначено стандартні категорії:

• ** Додано ** — нові можливості або можливості; « Додано підтримку перевірки підпису webhook »
• ** Змінено ** — зміни до існуючої функціональності; « Змінено типовий тайм- аут з 30 на 60 секунд »
• Застаріла — можливості, які будуть вилучені в майбутній версії; «Застаріла кінцева точка /v1/send — замість неї використовуйте /v2/messages»
• Видалено — можливості, які були вилучені; «Видалено застарілий XML API (застарілий з v2.0)»
• ** Виправлено ** — виправлення помилок; “Виявлено проблему, коли термін дії знаків сторінкування закінчувався через 10 хвилин замість 24 годин”
• ** Безпека ** — виправлення, пов’язані з безпекою; «Відомостями про вразливість крос-сайтового скриптингу на сторінці результатів пошуку»

Використання цих категорій на постійній основі дозволяє читачам швидко шукати те, що має для них значення. Розробник, який оновлює залежність, спочатку перевіряє « Зміни, що знижують продуктивність » і « Вилучені ». Зчитувач, що орієнтований на безпеку, спочатку сканує «Безпеку».

Зміни в комунікації

Зміни, які потребують особливих зусиль і спеціального мови:

• “BREAKING CHANGE:” — позначка з великими літерами, щоб не пропустити зміни
• «Це зміна, яка знищує, якщо ви…» — пояснює, хто саме зачеплений; «Це зміна, яка знищує, якщо ви зараз передаєте user_id як рядок — тепер це має бути ціле число»
• «Потрібна міграція» — сигнал, що розробник повинен вжити дій
• « Щоб мігрувати, замініть [старий] на [новий] » — найясніша з можливих інструкцій міграції
• «Ця зміна вступає в силу в v4.0» — вказування версії є обов’язковим
• «Клієнти, що використовують [функцію], повинні оновити перед оновленням до цієї версії» — встановлення чітких очікувань

Найбільш поширеною помилкою, яка призводить до порушення зв’ язку зміни, є нечітке повідомлення. « Ми змінили API » не допоможе. « Ми змінили тип відповіді поля amount з рядка на ціле число у кінцевій точці /payments. Клієнти, які обробляють це поле як рядок, будуть розбиті.” є точним і дійсним.

Написання ефективних описів виправлень помилок

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

• «Відкриття: «Відкриття» — це гра з ключем
• Strong: «Виявлена проблема, коли користувачі, які входили з Google SSO були перенаправлені на неправильну сторінку після скасування пароля»

У офіційних нотатках до випуску слово probe краще за bug, оскільки воно звучить менш тривожно для нетехнічно освічених читачів. « Виправлено проблему » — це більш м’ яке слово, ніж « Виправлено ваду »

Спільні шаблони:

• «Виявлено проблему, де [стан] спричинив [проблему]»
• «Розв’язано умову гонки в [компоненті], яка могла викликати [симптом] під високим навантаженням»
• «Відомі люди, які вчинили злочин» (англ. The Known People Who Did the Crime) (1999) (англ.)

Консульська мова

Виправлення безпеки використовують певний словник:

• CVE — ідентифікатор для публічно відомої вразливості; «Addressed CVE-2024-12345 affecting the XML parser»
• «Ми настоятельно рекомендуємо оновлення» — тверда рекомендація, використовується для серйозних вразливостей
• «Ця вразливість дозволяє автентифікованому користувачеві…» — описуючи вплив
• «Не існує відомого активного використання цієї вразливості» — зменшення тривоги, коли це необхідно
• «Це виправлення було зроблено [дослідником] через нашу програму відповідального розкриття» — з посиланням на дослідників безпеки

Покращення комунікації (не тільки виправлення)

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

• «Повніша продуктивність [функції] приблизно на 40%» — кількісне вираження поліпшення
• « Зменшення використання пам’ яті в [компонент] від X до Y » — конкретне і вимірюване
• « Розширено повідомлення про помилку для [операції], щоб включати назву поля, яке спричинило помилку перевірки » — опис покращень з точки зору користувача
• «Додано підтримку сторінкування до [endpoint] — раніше обмежено 100 результатами, тепер підтримує до 10 000»

Ключовий словник

Term	Definition
changelog	A file recording all notable changes to a project, organised by version
breaking change	A change that requires existing users to modify their code or configuration
Added	Changelog category for new features or capabilities
Fixed	Changelog category for bug corrections
Deprecated	Changelog category for features scheduled for future removal
migration	The process of updating existing code to work with a new version
CVE	Common Vulnerabilities and Exposures — an identifier for a known security issue
responsible disclosure	A process where security researchers privately report vulnerabilities before publication
issue	A polished term for a bug, preferred in external-facing release notes
semantic versioning	A versioning scheme where the version number communicates the type of change

Практичні поради

1. ** Написати замітки щодо випуску ваших останніх трьох запитів на звантаження. ** Навіть внутрішні зміни краще описати. Вправляйтеся з шаблоном: « [Категорія]: [Що змінилося і як це вплинуло на користувача] ». За допомогою цього шаблону буде легше переглядати ваші PR, а також краще повідомляти про нові випуски.

2. ** Завжди вказати кількісні показники покращення продуктивності. ** « Швидше » не має значення; « 50% швидше під навантаженням більше 1000 одночасних запитів » є корисним. Практикуйте запитання себе: «Чи можу я додати число тут?»

3. ** Написати описи змін з точки зору користувача. ** Не « Ми змінили тип даних amount », а « Якщо ваш код читає amount як рядок, вам слід оновити його, щоб читати як ціле число. Код, який не робить цю зміну, отримає помилку 400 після оновлення до v3.0.”

4. ** Читання журналів змін з Stripe, GitHub і Vercel. ** Ці компанії відомі чудовим написанням записів про випуск. Зауважте, як вони балансують технічну точність з доступністю, як вони позначають пошкоджені зміни і як вони описують виправлення безпеки.

Conclusion

Словниковий запас повідомлень про випуск — додано, виправлено, змінено, застаріло, міграція, CVE — відповідає послідовним шаблонам, які роблять технічне спілкування ясним і професійним. Добре написані замітки щодо випуску зменшують кількість запитів на підтримку, збільшують довіру користувачів і роблять ваш продукт більш привабливим. Для людей, для яких англійська не є рідною мовою, оволодіння стандартними шаблонами написання changelog є високо переносимим — однаковий словник і структура з’являються в кожному добре запущеному проекті з відкритим кодом і професійному програмному продукті. Почати з угоди « Зберігати журнал змін » і збиратися з цього місця.

В практиці: покращення комунікації для глобальної команди

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

Однією з найчастіших проблем є опис розривних змін. Просто сказати «Ця версія вводить різку зміну» недостатньо. Потрібний контекст. Кращий підхід буде таким: «Це видання включає зміну кінцевої точки API /users/{id}. Попередньо, ця кінцева точка приймала як ціле число, так і рядок ідентифікаторів. Тепер, він приймає тільки цілі числа. Ця зміна є необхідною через [коротко поясніть причину — наприклад, збільшення навантаження на сервер] і може вимагати від клієнтів оновлення їхнього коду інтеграції. » Ключовим у цьому випадку є чітке вказати * що * змінилося, * де * це змінилося, * чому * це змінилося (не занурюючись у надмірні подробиці), а також потенційний вплив на користувачів. Уникайте жаргону, де це можливо, або негайно поясніть його.

Іншою областю, що вимагає чутливості, є зворотній зв’язок під час перегляду коду. Отримати коментарі типу «Це потребує більше роботи» може бути розчаруванням без контексту. Краще було б сказати: “Дякую, що звернули на це увагу! Можеш роз’яснити, що саме потребує уваги? Наприклад, чи є якісь потенційні проблеми з продуктивністю з цією реалізацією, або вона не відповідає нашим існуючим стандартам кодування? “Фармування конструктивного зворотного зв’язку - зосередження на * коді * і його впливі, а не на суб’єктивному судженні - має вирішальне значення. Аналогічно, при описі змін у описі Запиту на завантаження використовуйте дієслова дії, які чітко вказують на виконану роботу: « Реалізовано автентифікацію користувача за допомогою OAuth 2. 0 », замість « Виправлено автентифікацію. »

Нарешті, пам’ятайте, щоб бути уважні до рівнів формальності. Хоча швидке повідомлення Slack може дозволити більш неформальну мову («Тільки що знищив баґ!»), Офіційні повідомлення про випуск вимагають більш високого рівня професіоналізму і точності. Послідовність у стилі написання у всіх каналах спілкування значно покращить ясність і зменшить потенційні непорозуміння.

Ось приклад використання git diff для підсвічування змін, внесених у звіті:

git diff --color-words HEAD~1 HEAD

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