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

Хороший опис запиту на витягнення виконує більшість роботи з перегляду коду до того, як залишиться один коментар — він повідомляє переглядачеві, що змінилося, чому це змінилося, і як підтвердити, що це дійсно працює, щоб вони могли зосередити свою увагу на самому коді замість того, щоб зворотно розробляти ваші наміри. У цьому підручнику розглянуто формулювання, за допомогою якого опис PR можна швидко переглянути і легко довіряти йому.

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

** Краткое изложение « что » ** — резюме зміни у одному або двох реченнях, написане так, щоб людина, яка переглядає список PR, зрозуміла зміну без відкриття файла diff.

• “Я коротко описав, що: ця PR додає логіку повторення з експоненціальним відступом до обробника webhook платежів.” *

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

• “Я пояснив чому: доставка webhook вимикається без повідомлень під час коротких перерв у роботі, і у нас немає механізму повторних спроб.” *

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

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

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

• “Я надав шлях перевірки: запустіть включений пакет тестів або вручну викликайте локальну помилку webhook за допомогою наданого скрипту імітаційного сервера.” *

** Явно позначати ризик або обсяг** — викликати будь- що незвичне щодо радіусу зміни, наприклад, торкання спільної бібліотеки або вплив на шлях з високим рівнем навантаження.

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

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

• «Ця PR [додає/виправляє/переробляє] [спеціальну річ], тому що [спеціальна проблема або мотивація]»
• «Працював, [стара поведінка]; тепер, [нова поведінка]»
• «Щоб перевірити: [специфічні кроки, наприклад, запустити тести, перевірити цей знімок, відтворити локально з X].»
• «Ця зміна стосується [конкретної області] і не впливає на [пов’язану область]»
• «Зауваження: це залежить від того, чи [зв’язана PR/config зміна] буде об’єднана/розгорнута спочатку»

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

Повний, добре структурований опис:

• “Ця PR додає логіку повторних спроб з експоненційним відхиленням до обробника webhook платежу, оскільки доставка webhook вимикається без повідомлень під час коротких перерв у роботі нижнього рівня без механізму повторних спроб. Кількість повторних спроб обмежено п’ ятьма з перериванням, щоб уникнути перевантаження служби, що виконує перенесення. Щоб перевірити: запустіть npm test webhook-retry, або використовуйте включений скрипт мокрого сервера для імітації перехідної помилки локально.”*

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

Явно викликати область дії для зміни спільної програми: “Це стосується спільного HTTP- клієнта, який використовується службами розрахунків і сповіщень, тому я запустив обидва їхні тестові пакети локально для перевірки на відповідність цим змінам і підтвердив відсутність регресії.”

Опис рефакторизації без зміни поведінки:

• “Це чистий рефакторинг — вилучення логіки повторних спроб у спільну утиліту — без зміни поведінки. Всі існуючі тести проходять без змін.”*

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

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

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

1. Напишіть резюме з двох речень « що » і « чому » для гіпотетичного PR виправлення вади.
2. Написати шлях перевірки для PR, який не обробляється автоматичними перевірками.
3. Напишіть речення, у якому буде зазначено, що зміна стосується спільного коду, який використовується іншою командою.

Наприклад, англ. browsing: перегляд, пошук

Будьмо чесними — отримання відгуків на ваші запити на завантаження іноді може здатися… неприємним. Легко прийняти критику особисто, особливо коли ви зосереджені на самому коді. Однак, ключовим елементом ефективного співробітництва є не тільки написання хорошого опису PR; це розуміння і конструктивна відповідь на отриманий зворотній зв’язок. Багато молодих розробників борються з цим, тому що вони інтерпретують негативні коментарі як особисті невдачі, а не можливості для поліпшення.

Розглянемо цей сценарій: Сара надіслала запит на оновлення потоку розпізнавання користувача, але переглядач, Девід, залишив коментар, у якому сказано: « Потрібно більше контексту — неясно, яку проблему слід розв’ язати ». Початкова реакція Сари може бути оборонною — « Я думав, що це було зрозуміло! » Але кращою відповіддю, заснованою на професійній англійській мові і розумінні потоку спільної роботи, було б підтвердити зворотній зв’ язок, продемонструвати бажання навчитися і попросити про пояснення. Добрим продовженням може бути: «Дякую, що звернув на це увагу, Девід. Я вдячний, що ви підкреслили, де контекст можна поліпшити. Можете ли вы уточнить, какую информацию вы искали? Чи існує певний аспект потоку розпізнавання, який вас хвилює?» Зауважте, що за допомогою цього пункту ви уникнете захисних дій і відкриєте діалогове вікно.

Іншою поширеною ситуацією є отримання зворотнього зв’ язку через Slack — можливо, швидке повідомлення від члена команди, що каже: « Гей, чи можете ви додати коротке пояснення, чому ви змінюєте назву цієї змінної? » Негайний імпульс може бути відповіддю з чимось коротким, наприклад, « Тому що це було заплутано. » Це рідко допомагає. Замість цього, більш лаконічною відповіддю буде підтвердження пропозиції і пояснення вашого аргументу: « Добра думка! Я перейменував змінну з x на user_id для більшої ясності і відповідності з правилами назв нашого проекту. » Додавання цього рівня деталізації показує, що ви цінуєте найкращі практики і активно прагнете до спільного розуміння.

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