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

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

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

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

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

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

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

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

Структурування оголошення

• ** Що нового **: “API v3 вводить сторінкування на основі курсора, уніфікований формат відповіді на помилки, і підтримку OAuth 2.1 на всіх кінцевих точках.”
• Що змінюється для існуючих інтеграцій: “Якщо ви на v2, зауважте, що параметри запиту page і limit замінені на cursor і pageSize в v3.”
• Timeline: “версія 2 не буде негайно виключена з використання — вона буде повністю підтримуватися до [дата], що дасть вам шість місяців на перехід.”
• ** Як мігрувати **: “Наш посібник з міграції на [посилання] описує кожну зміну з прикладами до/ після. Ми також надаємо скрипт перевірки сумісності, який ви можете запустити проти вашої інтеграції.”
• ** Підтримка під час перенесення **: « Якщо ви зіткнетеся з проблемами під час перенесення, наша команда підтримки розробників може допомогти вам за адресою [contact] з питань, пов’ язаних з перенесенням з версії 2 на версію 3. »

Пояснення аргументів

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

Обробка питань розробників

• «Так, v2 продовжить працювати так само, як і сьогодні, до дати заходу сонця — немає поспіху, але ми рекомендуємо почати міграцію раніше, а не ближче до терміну»
• Для більшості інтеграцій, зміна сторінки є єдиною зміною, з якою ви зіткнетеся — розділ «Швидкі перемоги» керівництва з міграції охоплює це конкретне оновлення першим
• Якщо шість місяців не достатньо часу для вашої конкретної інтеграції, зверніться до нас безпосередньо — ми можемо обговорити розширену хронологію для складних міграцій

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

1. ** Відокремте « що нового » від « що пошкоджено ». ** Розробники, які сканують оголошення, повинні негайно знайти розділ, який повідомляє їм, чи потрібно змінити їх код.
2. ** Завжди надавайте паралельне вікно підтримки, а не жорстке перенесення. ** Щедрий період перенесення є найбільшим фактором, який впливає на те, наскільки гладко пройде перенесення версії у вашій екосистемі.
3. ** Надати посібник з міграції, а не лише журнал змін. ** Журнал змін повідомляє розробникам про те, що змінилося; посібник з міграції говорить їм, що саме робити з цим.

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

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

Зв’язані ресурси

• Як повідомити про зміну обмеження API Rate в англійській мові
• Як написати повідомлення про знищення API англійською мовою
• Як написати посібник з міграції між основними версіями

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

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

Однією з ключових областей, де це проявляється, є фрази, пов’язані з * застарілістю *. Фрази на кшталт «старі версії» можуть відчуватися відверто або навіть неповажно, коли перекладаються безпосередньо. Замість того, щоб просто сказати «Версія 1.0 застаріла», розгляньте альтернативи, такі як: «Ми перейшли до версії 2.0, яка пропонує значні поліпшення і нові можливості. Хоча версія 1. 0 продовжить працювати протягом певного часу (як описано у нашому посібнику з міграції), ми заохочуємо вас мігрувати ваші програми, щоб забезпечити постійну підтримку і доступ до останніх розширень. У цьому підході використовується більш ввічлива мова — « перехідний період », « значні поліпшення » — і негайно направляє їх до відповідної документації. Аналогічно, коли ви описуєте зворотну сумісність, уникайте надто технічного жаргону, на зразок « несумісність бінарних даних ». Краще було б сказати: « Це оновлення зберігає сумісність з вашим існуючим кодом, тобто вам не слід робити значних змін, щоб інтегрувати його. »

Іншим поширеним викликом є створення чітких інструкцій міграції. Розробники часто користуються покроковим посібником, представленим простою мовою. Повідомлення Slack, що вимагає від розробників оновити свої інтеграції, може виглядати так: «Привіт команда! Ми випустили версію 2. 0 API з деякими цікавими новими можливостями. Будь ласка, перегляньте посібник з міграції [посилання] і дайте нам знати, якщо у вас є якісь запитання — ми тут, щоб допомогти!» Під час перегляду коду, коментар може бути таким: « Відмінна робота над цим PR. Щоб пояснити, чи можете ви додати до опису зауваження, у якому згадати, що розробникам, які використовують старі версії, слід оновлювати свої виклики, щоб використовувати нову кінцеву точку? Щось на зразок: «Розробники, які мігрують з версії 1.x, повинні замінити old_endpoint() на new_endpoint()?’» — надання конкретного прикладу допомагає уникнути неоднозначності і демонструє чіткі очікування.

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