Open Source Contribution English: PRs, Issues, and Community Interaction (англійською)

Introduction

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

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

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

Хороший звіт про помилку має чітку структуру. Майже всі основні проекти з відкритим кодом використовують ті ж самі три розділи:

• ** Кроки для відтворення: ** Пронумерований список того, що ви робили до появи вади.
• ** Очікувана поведінка: ** Те, що ви думали, що станеться.
• ** Фактична поведінка: ** Що насправді сталося замість цього.

Приклад добре написаного звіту про помилку:

Кроки для відтворення:

1. Європейський Союз Встановити версію пакунка 3. 2. 1. 2-й. Викликати client.connect() зі значенням тайм- аута 0. 3-й. Спостерігайте за виведенням термінала.

• Нет, не надо ** Очікувана поведінка: ** Клієнт повинен негайно викинути TimeoutError.
• Нет, не надо ** Фактична поведінка: ** Клієнт зависає на неопределенный час без виведення помилки або запису повідомлення у журнал.
• Нет, не надо ** Середовище:** Node.js 20.11, macOS 14.4, пакунок версії 3.2.1.

Корисні фрази для проблем:

• • “Я вважаю, що це може бути пов’ язано з проблемою # 234, але коренева причина виглядає по-іншому.” *
• “Я зміг відтворити це послідовно на Node.js 20, але не на Node.js 18.”
• • “Чи готові супроводжувачі до співпраці з цією програмою? Я радий подивитися, якщо так.»*

Для ** запитів на нові можливості *, поясніть проблему, яку ви намагаєтеся розв’ язати, перш ніж запропонувати рішення: * « Зараз немає можливості налаштувати затримку повторення спроби. Це ускладнює використання бібліотеки у середовищах з обмеженою швидкістю. Чи можливо додати опцію retryDelay?»

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

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

1. ** Що робить ця PR ** — одне або два речення. * “Ця PR вирішує проблему витоку пам’ яті, повідомленої у випуску # 412, випускаючи слухач подій у методі очищення.” *
2. ** Чому ви обрали цей підхід** — * “Я обрав цей підхід, оскільки він уникає торкання публічного API і відповідає тому, як бібліотека обробляє очищення в інших місцях.” *
3. Як перевірити це — “Щоб перевірити виправлення, запустіть npm test -- --grep 'cleanup'. Ви також можете відтворити початковий витік, повертаючи цей запит і спостерігаючи за використанням пам’яті в моніторі активності.”
4. ** Порівняльні проблеми ** — Використовуйте фразу * « Закриває # 412 » *, щоб автоматично закрити пов’ язану проблему, коли PR буде об’ єднано.

Поширені фрази опису PR:

• “Це PR адреси…”
• • “Ця зміна вводить…” *
• “Я вибрав цей підхід, тому що…”
• • “Це зміна, яка змінить все — дивіться зауваження щодо переходу нижче.” *
• • « Виправлення # [номер проблеми] » * / * « Закриття # [номер проблеми] » * / * « Повязано с # [номер проблеми] » *

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

Відповідь на питання підтримувачів та переглядачів

Перегляд коду в відкритому коді може здатися жорстким на початку. Коментарі часто короткі і прямі. Навчання правильно читати їх і відповідати професійно є важливим навиком.

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

• ** LGTM ** — « Виглядає добре для мене ». Рецензент затверджує вашу зміну.
• ** nit ** — скорочення від « nitpick ». Дуже незначна пропозиція, часто необов’ язкова. * “nit: можна перейменувати цю змінну на connectionPool для зрозумілості.” *
• ** blocking ** — коментар, який слід ввести перед тим, як можна буде об’ єднати PR.
• ** non- blocking ** — Пропозиція або питання, яке не перешкоджає об’ єднанню.

Відповідаючи на зворотній зв’ язок щодо перегляду, завжди підтверджуйте коментар перед тим, як пояснити своє рішення:

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

Коли супровідник закриває вашу проблему або відкидає ваш PR, відповідайте з повагою. Спільнота невелика, і ваша репутація йде за вами:

• “Дякую за пояснення - це має сенс. Я буду стежити за списком листування, якщо я знайду інший підхід.”

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

Term	Definition
pull request (PR)	A proposal to merge your code changes into a project’s main codebase
issue triage	The process of reviewing, labelling, and prioritising open issues
upstream	The original repository that a fork was created from
fork	A personal copy of a repository where you make changes before submitting a PR
LGTM	”Looks Good To Me” — an informal approval from a reviewer
nit	A very minor, often optional code style suggestion left in a review
breaking change	A change that is incompatible with previous versions of the software
good first issue	A label used by maintainers to mark issues suitable for new contributors

Практичні поради

1. ** Починайте з міток « хороший перший випуск ». ** Більшість великих проектів містять мітки для випусків, які зручні для початківців. Пошук GitHub для label:"good first issue" плюс мова або framework, що вас цікавить.
2. ** Перед відкриттям будь- чого прочитайте файл CONTRIBUTING. md. ** У проектах є певні правила щодо форматування звітів, запуску тестів і написання описів PR. Ігнорування цього файла — найшвидший спосіб відхилення вашого внеску.
3. ** Спочатку напишіть опис вашої проблеми або PR у текстовому редакторі. ** Перечитування опису перед надсиланням допоможе вам виявити неясні речення і відсутню інформацію.
4. ** Будьте терплячими з часом відповіді. ** Більшість супроводжувачів відкритого коду є волонтерами. Очікування від одного до двох тижнів перед ввічливим продовженням вважається нормальним: * “Просто продовжуйте це - раді відповісти на будь-які запитання або внести зміни, якщо це потрібно.” *

Conclusion

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

Стиль мовлення: вільний стиль

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

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

Іншою областю, де нюанс є критичним, є поводження з критикою. Отримати негативний відгук може бути особистим, особливо коли ви не знайомі з культурними очікуваннями щодо перегляду коду. Спробуйте переглянути ситуацію як можливість для навчання і вдосконалення. Фрази на кшталт «Дякую за позначення цього» або «Я ціную вашу пропозицію щодо…» демонструють готовність навчатися і пристосовуватися. Якщо ви не погоджуєтесь з коментарем, з повагою вкажіть ваші аргументи, знову ж таки зосередившись на технічних аспектах, а не на особистих почуттах. Уникайте захисної мови — фрази на кшталт «Це не так, як я це зробив» рідко допомагають.

Нарешті, не недооцінюйте важливість ввічливої фрази на каналах або форумах Slack. «Прошу» і «дякую» йдуть довгий шлях, навіть якщо ваша англійська не ідеально відшліфована. Просте визнання чогось іншого («Дякую за підказку!») показує повагу і сприяє позитивному середовищу спільноти.

Ось приклад використання git diff для підсвічування змін у описі PR:

git diff --color-words HEAD~1 HEAD

За допомогою цієї команди можна створити кольоровий вивід, у якому буде показано, які саме слова було додано, вилучено або змінено між двома зобов’ язаннями, що надасть вам можливість отримати чітке візуальне представлення ваших змін. Після цього ви можете включити цей вивід (або його очищену версію) до опису PR, щоб надати переглядачеві контекст.