English for Writing a Migration Guide Between Major Versions

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

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

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

** Codemod ** — автоматизований скрипт, який переписує код відповідно до нового API, зменшуючи кількість роботи, необхідну для перенесення. “Ми опублікували код-мод, який автоматично обробляє більшість переписів — запустіть npx migrate-tool v3 перед тим, як робити будь-які зміни вручну, оскільки він буде обробляти механічні частини.”

** Приклад до/ після** — парний фрагмент коду, у якому показано старий шаблон і новий шаблон поруч один з одним, це єдиний найефективніший формат для керівництва з перенесення. “Перед: client.fetch(url, callback). 1971. с. 128. API, заснований на callback, був повністю видалений на користь обіцянок. ”

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

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

• “Старий клас Client все ще працює у версії 3, але він застарілий і записує попередження консолі. Він буде повністю видалений у v4, тому зараз час мігрувати». *

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

• “Перед: [старий код]. Після: [новий код].”
• «Це різка зміна: [що змінилося] означає [що вам потрібно оновити]»
• “Спочатку запустіть codemod: [команда]. Він обробляє [X] автоматично; вам потрібно буде вручну оновити [Y].”
• «Не існує прямого шляху міграції з [старої версії] до [нової версії] — спочатку оновлювати через [проміжну версію]»
• «Оцінений час міграції: [X], залежно від того, скільки вашої кодової бази використовує [захищений API]»

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

Відкриття майстра перенесення з резюме обсягу: “Це керівництво стосується переходу з v2.x на v3.0. Основні зміни: видалення API, заснованого на callback, на користь обіцянок, нове обов’язкове поле apiVersion в конфігурації клієнта, і перейменування fetchAll на list. Більшість проектів можуть завершити цю міграцію за менше ніж годину.”

Запис пари до/ після з поясненням, чому вона змінилася:

• “Перед:

client.fetch(url, (err, data) => { ... });

Після:

try {
  const data = await client.fetch(url);
} catch (err) { ... }

Callback API було вилучено на користь обіцянок, що краще підтримує асинхронні / очікувані шаблони, які більшість споживачів вже використовували через обгортку. ”*

Бути чітким щодо того, що код- мод робить і не робить: “Codemod ( npx migrate-tool v3 ) автоматично переписує виклики, засновані на callback, для використання async/await. Він не переписує нестандартну логіку обробки помилок, яка розгалужується на старі коди помилок, засновані на рядках — вам потрібно буде оновити їх вручну, і ми позначили кожне випадок з коментарем // TODO(migrate) для вас, щоб знайти їх.”

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

• “Зауваження: це не просто зміна синтаксису. У v2, list() повертає результати в порядку вставки. У v3, list() повертає результати в порядку updatedAt за замовчуванням. Якщо ваш код залежить від порядку вставки, передайте { sort: 'created' } явно, щоб зберегти стару поведінку.”*

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

• Структуруйте кожну зміну як ** пару кодів до/після **, а не просто опис в прозі — код є однозначним у тому сенсі, що речення, що описує код, часто не є.
• Явно вкажіть ** що codemod обробляє і що він не обробляє ** - незавершена ментальна модель автоматизації обсягу призводить до того, що люди або пропускають необхідну ручну роботу, або переробляють роботу, яку codemod вже зробив.
• Розрізняйте ** зміни синтаксису ** від ** змін поведінки ** — перейменування є небезпечним, але зміна типової поведінки (наприклад, порядку впорядкування) може призвести до тихих помилок, які не буде показано як помилки, і заслуговує на особливу увагу.
• Якщо не існує прямого шляху міграції між двома версіями, скажіть про це на самому початку керівництва — виявити це на півдорозі оновлення набагато більше розчарування, ніж сказати вам це на початку.
• Надавайте ** приблизну оцінку часу ** для переходу, навіть приблизну — це допомагає читачам планувати роботу і сигналізує про те, що ви подумали про їхній досвід, а не просто задокументували зміни.

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

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

Національні мови: мова ненаціональних меншин

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

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

Іншою проблемою є використання пасивного голосу, який може затемнити відповідальність. Опис PR може виглядати так: « Схему бази даних було оновлено ». Це не говорить нікому, хто зробив зміну або чому. Ефективнішою формулюванням буде: « Джон змінив схему бази даних, щоб вмістити нову інтеграцію API. » Прозорість створює довіру і розуміння — це про чітке вказівок, хто відповідає за кожен аспект міграції. Аналогічно, під час перегляду роботи колеги, уникайте нечітких коментарів на зразок « Це потрібно виправити ». Замість цього спробуйте « Чи можете ви пояснити причину цієї зміни? Зокрема, як це збігається з документованим шляхом міграції?»

Нарешті, пам’ятайте про ідіоми і розмовні вирази. Фрази на кшталт « розбити зміни » або « відкинути » не можуть бути перекладені безпосередньо і можуть бути легко неправильно інтерпретовані. Краще використовувати точні слова: « Це оновлення вводить несумісні зміни до інтерфейсу API ». Або, під час обговорення потенційних проблем, вказати: « Якщо користувач відчує помилки під час процесу оновлення, він може повернутися до попередньої версії за допомогою кроків, описаних у Додатку А. » Такий підхід є більш зрозумілим і менш залежить від припущень. Пам’ятайте, що чіткість є найважливішою; вона зменшує неоднозначність і забезпечує, що кожен - незалежно від їх рідної мови - може успішно керувати міграцією.