Як писати Changelog англійською мовою

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

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

** Додано / Змінено / Виправлено / Вилучено ** — стандартні заголовки категорій, які відповідають таким правилам, як Зберігати журнал змін, які групують записи за типом змін, які вони представляють, надаючи користувачеві змогу шукати категорію, яка його цікавить.

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

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

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

• “Переписати цей запис — « перероблено внутрішній шар кешування » описує деталі реалізації, які ніхто з користувачів бібліотеки не бере до уваги. Якщо це поліпшило час відповіді, скажіть, що: «покращено середній час відповіді на 30% для повторних запитів»

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

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

• Чи можна це зробити, змінивши або виправивши?»
• Чи це насправді зміна, або це зворотно сумісний?»
• Чи описує цей запис вплив, який має значення для користувача, або це просто деталь реалізації?»
• Чи потрібно цей переломний момент зміни міграційної ноти з прикладом?»
• Чи хтось, хто сканує цей changelog, зрозуміє, що їм потрібно зробити перед оновленням?»

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

Запис запису з чіткою категорією:

• ”### Виправлено — Виправлено проблему, коли фільтри дати, що використовують нетиповий часовий пояс, повертали результати, які були на один день пізніше середи. Це вплинуло на будь-який запит, що використовує параметр timezone з не-UTC значенням.”*

Виклик зміни, що перериває, чітко:

• ”### Breaking Change — Функція fetchUser(id) тепер повертає Promise замість прийняття зворотного виклику. Існуючі виклики, засновані на зворотному виклику, повертатимуть помилку застарівання. Див. зауваження щодо міграції нижче для оновленого синтаксису.”*

Запис нотатки щодо перенесення: *“Примітка щодо міграції: замінити fetchUser(id, callback) на const user = await fetchUser(id). Якщо ви не можете використовувати async/await в цьому контексті, замість цього обгорніть виклик у fetchUser(id).then(callback)

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

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

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

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

Навігація Нуанси: підтримка мови для не-національних розробників

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

Однією з найчастіших проблем є використання надто буквальних перекладів. Наприклад, якщо ви документуєте виправлення вади вашою рідною мовою, ця фраза може бути перекладена як « Розв’ язано проблему з неправильним обчисленням ». У англійській мові це звучить незграбно і не передає * впливу * зміни. Замість цього, скористайтеся такими формулюваннями, як « Виправлено помилку обчислення, що призвела до неточності результатів », або, ще краще, « Виправлено ваду у модулі обчислень, що призвела до помилкових даних ». Останнє є більш професійним, точним і негайно зрозумілим. Зверніть увагу на дієслова - послідовне використання теперішнього часу («ми виправили») проти простого минулого («ми виправили») може значно вплинути на ясність.

Іншою областю, яка потребує ретельного розгляду, є «перервати зміни». Безпосереднє перекладання фраз, таких як «головний розлад» або «значна зміна», може здатися відповідним в деяких контекстах, але їм бракує точності. Краще описати, що саме пошкоджено і як це впливає на користувачів або інші частини системи. Наприклад, замість того, щоб сказати «Це оновлення вводить різку зміну», ви б сказали: «Видалена підтримка для застарілого API версії 1.0. Це вимагає від розробників мігрувати свої програми, щоб використовувати версію 2.0. “Додавши коротке пояснення * чому * зміна була зроблена - навіть якщо це просто “для поліпшення продуктивності” - ще більше покращує розуміння.

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