Як пояснити семантичні рішення версії англійською мовою

Визначення того, чи є зміна латом, незначною, або головною версією під семантичним версуванням (semver) часто є судовим викликом, і пояснення цього суду чітко англійською мовою — в описі PR, журналі змін або обговоренні супроводжувачів — є власною вмінням. Цей посібник містить словниковий запас і шаблони обґрунтування для виклику і переконливого повідомлення.

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

** Patch version ** — версія для виправлення помилок, які не змінюють поведінку публічного API, на якій можуть покладатися виклики.

• “Це латка — ми виправили помилку off- by- one у логіці сторінкування, але підпис функції і задокументована поведінка залишилися незмінними.” *

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

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

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

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

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

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

• Це має бути великий удар — це усуває публічну функцію»
• Я б класифікував це як незначну версію, оскільки це чисто додаткове
• «Навіть якщо це виглядає невеликим, це змінює задокументовану типову поведінку, тому це повинна бути головна версія»
• Це внутрішнє і не торкається публічного API, тому це патч
• Ми відкидаємо це в незначному випуску зараз, з видаленням, запланованим на наступний великий випуск. “

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

Обґрунтування вибору версії у описі PR:

• “Відновлення до версії 3. 4. 0 (незначна), а не латка, оскільки це додає новий параметр retries до конструктора клієнта. Це необов’язково і за замовчуванням до старої поведінки, тому існуючі виклики не впливають, але це нова поверхня, яку semver розглядає як незначну, а не латку. ”*

Відсилання назад на запропонований номер версії у перегляді: “Я думаю, що це має бути головний удар, а не незначний. Зміна типового тайм-аута з 30s на 5s є зворотньо сумісною в тому сенсі, що підпис функції залишається тим же, але змінює поведінку, що виклики можуть бути безмовно залежними — це саме той вид змін, для яких існує основна категорія semver. ”*

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

Запис запису журналу змін, який пояснює причину:

• ”### Змінено (незначно) Додано додатковий прапорець strict до validate(). Існуючі виклики без прапора не впливають, тому це доставляється як незначна, а не головна версія. “*

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

• Обґрунтуйте свій вибір версії, назвавши що змінилося в публічній поверхні API, а не просто описуючи зміну коду — «це змінює задокументовану типову поведінку» переконливіше, ніж «це більша зміна»
• Якщо ви не знаєте, що робити з латку і незначною, запитайте: « Чи додано щось нове, від чого виклик може залежати?» Якщо так, це незначна, навіть якщо не було порушень коду.
• Якщо ви сумніваєтеся, чи слід використовувати невелику чи велику змінну, запитайте: « Чи може ця змінна беззвучно вбити когось, хто покладається на стару поведінку, навіть без зміни підпису? » Якщо так, вважайте її великою.
• Використовуйте шаблон deprecate-then-remove для знищення змін, коли це можливо, і вкажіть це в журналі змін — це сигналізує користувачам, що ви обережніше ставитеся до шляху їхнього оновлення.
• У дискусіях про перегляд, це нормально не погоджуватися з класифікацією - просто переконайтеся, що ви обидва сперечаєтеся з “як виглядає публічна поверхня API для виклику”, а не з “яким великим це відчувається”

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

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

Наприклад, слово «семантична» вживається для позначення семантичної версії

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

Уявіть, що ви переглядаєте запит на збирання, який пропонує змінити версію з 1. 2. 0 на 1. 2. 1. Розробник, назовемо його Бен, додав незначне виправлення помилки. Опис Беном в PR-розсилці звучить так: «Вийшов патч». Хоча це технічно правильно, але не передає аргументів, що стоять за цим рішенням. Краще було б сказати щось на зразок: “Бен, це хороший полов! Позначити як випуск латку — це вирішує невелику, ізольовану проблему, яка не змінює фундаментально API або не вводить ніяких нових залежностей. Цей варіант підтримує зворотну сумісність і зменшує перешкоди для користувачів, які покладаються на версію 1. 2. 0. Зауважте використання таких фраз, як « вирішує невелику, ізольовану проблему », « не змінює API фундаментально » і « підтримує зворотну сумісність ». Ці фрази є ключовими для передачі ваших намірів.

Інша ситуація може виникнути в розмові Slack під час перегляду коду. Хтось запитає: «Чому ви випустили 1.3.0?» Корисною відповіддю буде: «Ми випустили 1.3.0, тому що це оновлення включає незначну функцію, яка покращує продуктивність і відповідає змінюючимся потребам наших користувачів, але не порушує існуючої функціональності. Це крок вперед в еволюції бібліотеки без необхідності значних змін від споживачів.” Знову ж таки, зосередження на тому, * чому * зміна є вигідною і підкреслення зворотньої сумісності будує довіру.

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