How to Announce a Breaking Change in English

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

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

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

• “Переназва цього поля є зміною, яка призведе до руйнувань — будь- кому, хто розбирає відповідь за назвою поля, слід буде оновити свій код.” *

** Повідомлення про виключення з використання ** — попереднє попередження про те, що у майбутньому функціональність буде вилучено або змінено, що дає користувачам час для переходу до нової версії, перш ніж зміни, які призведуть до виключення з використання, насправді набудуть чинності. “Ми випускаємо сьогодні повідомлення про зниження якості для кінцевої точки v1; вона залишиться функціональною протягом 90 днів до вилучення.”

** Посібник з міграції ** — документація, яка пояснює, крок за кроком, як користувачі повинні оновлювати свій код для роботи з новою версією після зміни. “Довідник з міграції містить приклад коду, який показує, як саме оновити формат заголовка розпізнавання.”

** Дата закінчення дії ** — конкретна дата, з якої застаріла функціональність або версія перестане працювати повністю.

• “Дата закінчення дії формату webhook встановлено на 1 вересня — після цього буде надіслано лише нову структуру вантажу.” *

** Семантичне версування ** — спосіб версування, за якого приріст головної версії конкретно сигналізує про наявність змін, які знищують, відрізняючи їх від зворотньо сумісних незначних або латок. “Згідно з семантичною версією, ця зміна буде випущена як v3. 0. 0, а не v2. 5. 0, оскільки вона не сумісна з попередніми версіями.”

** Обратна сумісність ** — властивість нової версії, яка продовжує працювати правильно з кодом, написаним на основі попередньої версії, без потреби внесення змін.

• “Ми оцінювали підхід, який би зберігав зворотну сумісність, але це означало б підтримку двох несумісних форматів даних на неопределённый час.” *

** Період відстрочки ** — вікно часу між оголошенням про зміну і її дійсним введенням у дію, протягом якого, зазвичай, підтримується як стара, так і нова поведінка. “Ми пропонуємо 60-денний період відстрочки, коли доступні як старі, так і нові формати відповідей, які контролюються заголовком запиту.”

Звичайні фрази

• Це різка зміна і потребує оновлення з вашої сторони — ось саме те, що потрібно змінити»
• «Ми даємо 90-денний період пробачення, перш ніж стара поведінка буде повністю видалена»
• «Під час польоту ми побачили три найскладніші об’єкти, які коли-небудь бачили»
• «Ця зміна надходить як головний вибух версії, за семантичним версуванням, саме тому, що вона не є зворотньо сумісною»
• Якщо ви не зможете мігрувати до дати заходу сонця, будь ласка, зв’яжіться з нами — ми можемо обговорити продовження для підтверджених краєвих випадків
• «Ми знаємо, що це розлад, і ми намагалися зробити шлях міграції якомога коротшим»

Приклади висловлювань

Про оголошення зміни для користувачів API:

• “Починаючи з v3. 0. 0, кінцева точка /orders повертатиме total_amount як рядок замість числа, щоб уникнути проблем з точністю з плаваючою комою, про які повідомляли деякі інтегратори. Это разрушительная перемена. Попередня поведінка залишається доступною на /v2/orders до дати заходу сонця 15 жовтня, надаючи вам 60- днівовий період для переходу. Повний перехід, включаючи приклади коду на трьох мовах, є в посиланні на посібник. *

Відповідь на запит користувача про більше часу:

• “Дякуємо за позначення обмежень вашої часової шкали. Ми можемо продовжити доступ вашого конкретного інтегрування до застарілого кінцевого пункту на додаткові 30 днів після загальної дати закінчення, враховуючи обсяг змін, необхідних на вашому кінці. Будь ласка, повідомте нас, як тільки ваша міграція буде завершена, щоб ми могли вимкнути розширення.”*

Пояснення причин внутрішньо перед публічним оголошенням:

• “Я б хотів запропонувати, щоб ми випустили це як основну версію з 90- днем грішного періоду, а не як беззвучну зміну, навіть якщо технічно виправлення невелике. Деякі з наших найбільших інтеграторів аналізують це поле за типом, і безшумна зміна пошкодить їхні системи без попередження, що є саме тим результатом, якому має запобігти чітке оголошення про зміну. “*

Професійні поради

• Завжди чітко вкажіть, що щось ** є зміною, що перервала ** - не закопуйте це нейтральною мовою, наприклад, “ми оновили формат відповіді”, що може призвести до того, що споживачі не зможуть це повністю пропустити.
• Включити ** дату закінчення ** в кожному оголошення про зміну, а не просто нечітке « у майбутньому випуску » — конкретна дата дозволяє споживачам фактично планувати свою міграцію.
• Надати ** посібник з міграції ** з реальними прикладами коду разом з оголошенням, а не як продовження — команди набагато швидше діятимуть, коли шлях вперед буде відразу видимим.
• Посилання ** семантичне версування ** явно, коли це застосовне — це дає технічним користувачам знайомий, однозначний сигнал про обсяг зміни, перш ніж вони навіть прочитають деталі.

Практичні вправи

1. Написати повідомлення у трьох реченнях про зміну у механізмі розпізнавання, включаючи дату закінчення дії та посилання на посібник з перенесення.
2. Сформулювати відповідь з двох речень клієнту, який вимагає продовження строку, пропонуючи розумний компроміс.
3. Поясніть, у двох реченнях, чому важливо мати головну версію, коли оголошується про зміну технічного рівня.

Мова мовлення: мова, що використовується в спілкуванні

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

Однією з ключових областей є використання умовної мови обережно. Фрази на кшталт «потрібен», «може» або «потенційно» можуть бути неправильно інтерпретовані як нечіткі пропозиції, а не конкретні інструкції. Замість того, щоб сказати: « API * може * змінитися », набагато ефективніше — і менш ймовірно, що це призведе до плутанини — сказати: « Ми вводимо нову версію API, яка ** вимагає ** оновлення вашої логіки інтеграції. » Включення « вимагає » негайно передає необхідну дію. Аналогічно, уникайте пасивного голосу, коли це можливо; активний голос демонструє відповідальність і ясність. Замість « Будуть внесені зміни » скористайтеся « Ми впровадимо ці зміни ». Цей варіант переносить фокус уваги з віддаленого процесу на конкретну дію, яку виконає команда розробників.

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

Нарешті, розгляньте тон. Хоча професіоналізм є ключовим, трохи вибачливий або надто обережний тон може ненавмисно створити відчуття невідкладності або негативності. Стрімайтеся до нейтрального, інформативного голосу. Хороший початок може бути таким: «Ми раді оголосити про майбутній випуск версії 2.0, яка включає кілька поліпшень і необхідних оновлень API. Ми розуміємо, що цей перехід може вимагати коригування вашого існуючого коду, і ми підготували докладні рекомендації щодо міграції [посилання на документацію], щоб підтримати вас у цьому процесі. “Це поєднує позитивні відчуття з ясним визнанням потенційно необхідних зусиль.