Англійська мова для внесків з відкритого коду: проблеми, PR і мова спільноти

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

Підготовка ефективних рішень

Добре викликане повідомлення дає супроводжувачам все, що їм потрібно для розуміння і відтворення проблеми. Неясні питання часто закриваються без коментарів або залишаються без відповіді місяцями.

Словник звітування про помилки

** Кроки відтворення ** — точна послідовність дій, необхідних для запуску вади. Завжди пронумеровані. Без кроків відтворення супровідник не зможе перевірити проблему. « Щоб відтворити: 1. Створити новий проект. 2. Запустити npm install. 3. Виконати npx build --watch. 4. Редагувати будь-який файл джерела.»

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

** Справжня поведінка ** — що насправді сталося. « Справжня поведінка: інструмент збирання завершує роботу з ненульовим кодом стану і не виводить повідомлення про помилку. »

MCVE (Minimal, Complete, and Verifiable Example) — приклад коду, що демонструє проблему з якомога меншою кількістю коду. Іноді називається MRE (Minimal Reproducible Example — мінімальний відтворюваний приклад). « Я долучив MCVE — проблему можна відтворити лише за допомогою цього 20- рядкового скрипту. »

Подробиці середовища — номери версій, операційна система і відповідна конфігурація. «Environment: Node.js 20.11.1, macOS 14.3, package version 2.4.0.»

** Регресія ** — вада, коли щось, що раніше працювало, перестало працювати, зазвичай, це відбувається через зміну певної версії. « Це регресія, введена у версії 2. 4. 0; поведінка була правильною у версії 2. 3. 9. »

** Обхідне рішення** — тимчасове рішення, яке уникає вади без виправлення її. « Обхідне рішення: встановлення прапора --legacy-peer-deps вирішує невідкладну проблему, але це не має бути необхідним. »

Використовується для написання фраз

Открывается ясно:

• «Я зіткнувся з помилкою у версії [X], яка викликає [спеціфічну поведінку]»
• «Це запит на функцію: Я б хотів запропонувати [X], тому що [причина]»

** Надання контексту: **

• “Я зіткнувся з цією проблемою під час [використання випадку]. Це впливає на [обсяг].”
• «Я шукав існуючі проблеми і запити на витягування і не знайшов дублікатів»

Вираз непевності:

• «Я не впевнений, чи це помилка, чи прогалина в документації — поведінка, яку я бачу, відрізняється від того, що описує README»
• Це може бути за проектом, в якому випадку я б привітав пояснення в документації. “

Запис описів запитів на завантаження

Добре написаний опис PR заощаджує час переглядачів і збільшує ймовірність того, що ваш внесок буде об’ єднано.

** PR опис словар’ я: **

• ** Резюме ** — коротке пояснення того, що робить PR і чому.
• ** Мотивація ** — проблема, яку вирішує ця PR, або поліпшення, яке вона робить.
• ** Зміни ** — список конкретних змін, які було внесено.
• ** Тестування ** — як ви перевірили зміни.
• ** Розрив змін ** — будь- які зміни, які не є зворотньо сумісними.

Опис PR, вступні фрази:

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

** Опис змін: **

• “Головна зміна - [X]. Це також вимагало оновлення [Y] тому що [причина].”
• “Я розділив це на три затвердження для легшого перегляду: перше - [X], друге - [Y], третє - [Z].”

** Запит на особливий перегляд: **

• «Я б був вдячний за відгуки, особливо на [розділі] — я не повністю впевнений у своєму підході там»
• «Логіка в [назва функції] є найскладнішою частиною; будь ласка, зверніть на неї особливу увагу»

Перегляд коду Фрази відповіді

Добре відповідати на відгуки про перегляд коду показує професіоналізм і робить співпрацю гладшою.

** Підтвердження та прийняття відгуку: **

• «Good catch — I have updated this in the latest commit.» (англійською)
• «Ви маєте рацію; я перероблю це, щоб використовувати існуючу функцію утиліти замість цього»
• «Fair point — я додав відсутній тестовий випадок.»

Прошу прояснити:

• “Чи можете ви пояснити, що ви маєте на увазі під [X]? Я хочу переконатися, що я розумію занепокоєння, перш ніж змінити його»
• «Я не впевнений, що я слідую за пропозицією — чи можете ви надати приклад того, що ви маєте на увазі?»

З повагою не погоджуюсь:

• “Я розумію твою думку, але я вибрав цей підхід через [причину]. Чи ви будете відкриті до обговорення, чи варто цього компромісу?»
• «Моє розуміння було таким, що [X] є рекомендованим шаблоном для цього випадку — чи я неправильно прочитав рекомендації щодо внесків?»

** Позначити щось як вирішене: **

• «Відновлено в commit [hash].»
• «Застосовано в останньому відгуку — будь ласка, дайте мені знати, якщо це вирішить вашу проблему»

Приклади OSS Communication Sentences

1. «Я відтворив цю помилку послідовно на Node.js 20 і 22; Я долучив MCVE, який демонструє проблему в менш ніж 30 рядках коду — не потрібні залежності від фрейму»

2. “Ця PR закриває #847, додаючи налаштовуваний тайм-аут до HTTP-клієнта; без цього, довготривалі запити блокують петлю подій на неопределённое время. Типовий тайм-аут встановлений на 30 секунд для збереження зворотної сумісності.”

3. «Я шукав існуючу проблему перед відкриттям цієї і знайшов # 612, але ця проблема описує іншу кореневу причину; Я впевнений, що це нова помилка, введена в v3.1»

4. “Дякую за відгук. Я розглянув всі три коментарі у останньому збереженні: перевірку нульових значень, яку ви позначили, відсутній тест для краю, і невідповідність назв змінних. Чи не могли б ви ще раз подивитись, коли у вас буде час?»

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

Викладає англійську мову, має диплом бакалавра з англійської мови

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

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

Крім того, звертаючи увагу на активний проти пасивного голосу може значно поліпшити ясність. Хоча пасивні фрази не є поганими за своєю суттю, надмірне їх використання в технічних описах може затьмарити відповідальність і ускладнити розуміння потоку змін. Замість « Ваду виправив Іван », ефективнішим підходом буде « Іван виправив ваду ». Це продемонструє власника і пояснить, хто вчинив відповідно. Аналогічно, коли ви описуєте вашу роботу у описі PR, уникайте нечітких тверджень на зразок « Я зробив деякі зміни. » Будьте конкретними: « Я переробив модуль розпізнавання для поліпшення безпеки і швидкодії, вирішивши проблему # 123. » Використання точних слів створює довіру і показує, що ви ретельно обміркували ваш внесок.

І, нарешті, не недооцінюйте силу ввічливої фрази. Відкритий код побудований на спільноті; невелика ввічливість може зробити багато. Замість того, щоб відкидати чиюсь пропозицію з “Це не спрацює”, спробуйте “Я ціную вашу точку зору. Чи могли б ви розібратися, чому такий підхід неможливий?” Навіть коли ви не погоджуєтесь, підтримання шанобливого тону сприяє продуктивному діалогу і зміцнює зв’язок спільноти. Сфокусування на конструктивному зворотньому зв’язку - визнання зусиль, а також ніжно пропонуючи поліпшення - є основою успішного співробітництва з відкритим кодом.