Англійська мова для внесків з відкритого коду
Англійські фрази і звичаї, які вам потрібні, щоб робити свій внесок у проекти з відкритим кодом — проблеми, запити на звантаження, перегляд коду і спілкування з спільнотою.
Внесок у проекти з відкритим кодом є одним з найкращих способів поліпшити як розробник - і одним з найбільш мовних інтенсивних видів діяльності в інженерії програмного забезпечення. Ви пишете проблеми, описи запитів на завантаження, коментарі щодо перегляду коду і повідомлення для обговорення — усе це публічно, англійською мовою, для супроводжувачів, які можуть бути волонтерами з обмеженим часом.
Простота, професійна англійська мова не лише про спілкування: це про повагу до часу супроводжувачів. Чим краще ви пишете, тим більша ймовірність того, що ваш внесок буде прийнятий.
Написання хорошого звіту про помилку
Відмінний звіт про помилку відповідає на три запитання: чого ви очікували, що насправді сталося і як хтось може відтворити це?
** Структура шаблона: **
** Заголовок: ** Описовий, конкретний — не « Це не працює »
** Очікувана поведінка: ** * « Натискання кнопки « Надіслати » має викликати перевірку форми і показувати помилки, якщо обов’ язкові поля порожні. » *
** Справжня поведінка: ** * “Натискання кнопки « Надіслати » надсилає форму без перевірки. Обов’язкові поля не підсвічені.”*
Кроки для відтворення:
- Європа Перейти до
/signup2-й. Не заповнювати поле адреси електронної пошти 3-й. Натисніть кнопку Надіслати 4-й. Зауважте, що не з’ являється помилка перевірки
** Середовище:** Node 20.11, Chrome 125, macOS 14
Додатковий контекст: “Це працювало правильно у версії 2.3.1. Я вперше помітив проблему після оновлення до 2.4.0.”
** Корисні фрази для звітів про вади: **
“Я вірю, що це регресія, введена в…”
“Я підтвердив, що це відбувається постійно з…”
“Я не зміг відтворити це з…”
- « Режим усунення: проблеми можна уникнути за допомогою… » *
Запис запитів на можливості
** Заголовок: ** « Додати підтримку нетипових шаблонів повідомлень про помилки »
- “Поки що повідомлення про помилки перевірки є твердо кодованими рядками. Для команд, що створюють локалізовані програми, це вимагає розгалуження логіки обробки помилок.*
- Я хочу запитати можливість передавати нетипові шаблони повідомлень про помилки за допомогою параметра налаштування. Це дозволить користувачам локалізувати повідомлення без зміни коду бібліотеки.*
Щасливий реалізувати це, якщо супроводжувачі погодяться з підходом — я б хотів підтвердити запропонований API перед початком роботи.”
Ключові елементи: вказати * проблему *, а не лише функціональність; пояснити * варіант використання *; запропонувати допомогу.
Запис опису запиту на завантаження
Хороший опис PR надає рецензенту все, що йому потрібно, не запитуючи:
** Що: ** * “Додає підтримку нетипових шаблонів повідомлень про помилки перевірки.” *
** Чому: ** “Відомо, що 234. Команди, що створюють локалізовані програми, зараз повинні розділити модуль перевірки, щоб налаштувати повідомлення про помилки. Це додає параметр
messagesдо конфігурації перевірки, який перезаписує типові значення.”
** Як: ** “Функція
createValidatorтепер приймає додатковий об’ єктmessages. Ключами є назви правил перевірки, значеннями — рядки або функції, які повертають рядки. Повний список перезаписуваних ключів є в оновленому README.”
** Тестування: ** * “Тестування модулів охоплюють всі сценарії перезапису повідомлень. Я також перевірив вручну в прикладному додатку, включеному в репо.”*
“Ні. Існуючі конфігурації без параметра
messagesпродовжують працювати як раніше.”*
Відповідь на зворотній зв’ язок від супровідника
** Прийняття змін: **
“Дякую за огляд — це справедливі оцінки. Я оновлю реалізацію, щоб вона відповідала існуючому шаблону і додам відсутні тестові випадки. ”
“Хороший пойманный. Я вставив виправлення в останній запит — будь ласка, погляньте ще раз, коли у вас буде хвилина.»*
Прошу прояснити:
- “Я не впевнений, що розумію цей коментар — чи могли б ви розширити, що ви маєте на увазі під « віддавати перевагу функціональному підходу »? Я хочу переконатися, що я розумію очікуваний шаблон, перш ніж я перероблю.»*
З повагою не погоджуюсь:
“Я вдячний за пропозицію. Я розглядав цей підхід, але він вимагав би зміни публічного API, чого я хотів уникнути, щоб зберегти сумісність з попередніми версіями. Я радий обговорити це далі, якщо ви відчуваєте сильно.”
** Коли PR закривається без об’ єднання: **
*“Дякую за розгляд цього питання — я розумію рішення. Я закрию вилку і продовжу використовувати обхідний шлях наразі. Якщо вимоги зміняться в майбутньому, я буду радий переглянути їх»
Ця остання відповідь має значення. Супроводжувачі пам’ ятають співробітників, які відповідають ласкаво.
Писання в обговореннях і гілки проблем
Додання інформації до існуючої проблеми:
“Я можу підтвердити це — я бачу таку ж поведінку на Windows 11 з Node 22. Я радий надати більш докладний слід, якщо це допоможе.»
Пропозиція допомоги:
“Я буду готовий подивитися на це, якщо це буде щось, що буде прийнято. Можете показать мне соответствующий код? Я новий для кодової бази, але знайомий з базовим шаблоном.”
Подводя итог долгой дискуссии:
- “Подсумую обговорення: головними запропонованими підходами є X і Y. X простіше, але не обробляє ребра регістру Z. Y обробляє все, але додає складності. Чи це правильно передбачає, перш ніж ми вирішимо про напрямок?» *
Відкритий код
| Phrase | Meaning / When to use |
|---|---|
| LGTM | Looks Good To Me — informal approval |
| WIP | Work in Progress — not ready for review yet |
| nit | Minor stylistic comment, not blocking |
| cc @name | Notify someone by mentioning them |
| PTAL | Please Take Another Look — after addressing feedback |
| bikeshedding | Debating trivial details; use: “I don’t want to bikeshed this, but…“ |
| upstream | The original project you forked from |
| downstream | Projects that depend on yours |
| cherry-pick | Apply a specific commit from one branch to another |
Внесок у відкритий код є як комунікаційним, так і технічним. Чиста, шаноблива і ретельна письмова комунікація робить ваші внески більш прийнятними, більш схильні до швидкого об’ єднання і більш схильні до довгострокової співпраці.
Наприклад, слово «навигатор» означає: «навигатор» — професійний навігаційний пристрій
Спільноти з відкритим кодом процвітають на ясному, короткому спілкуванні. Однак, простого писання не завжди достатньо; розуміння тонких нюансів професійної англійської мови в контексті розробника є ключовим для ефективного співробітництва і успіху проекту. Багато не-рідних носіїв знаходять себе в боротьбі з фразуванням, яке відчувається надто формально або, навпаки, занадто неформально для професійного навчання. Давайте розглянемо деякі поширені пастки і те, як вдосконалити свій підхід - особливо, коли йдеться про пошуки зворотнього зв’язку і запропонувати зміни.
Одна з найчастіших проблем виникає під час перегляду коду. Отримати коментар на кшталт: «Це потребує більше роботи» є неймовірно нечітким. Сильнішою відповіддю було б сказати: «Я помітив, що цей розділ може отримати користь від яснішого назви змінних згідно з угодами нашого проекту — конкретно, використовуючи camelCase замість snake_case. Чи можете ви дослідити переробку цих рядків?» Це демонструє розуміння стандартів команди і надає конкретну область для поліпшення, а не просто критикує сам код. Аналогічно, під час написання описів запитів на збирання, уникайте надмірно ентузіастичних заяв, на кшталт « Це дивовижно!» Замість цього зосередьтеся на об’ єктивних спостереженнях: « Цей PR вирішує повідомлену ваду, реалізовуючи [конкретну зміну]. Тести були оновлені, щоб відобразити ці зміни. ”Мета не в тому, щоб хвилюватися; це в тому, щоб чітко сформулювати що ви зробили і чому.
Недбалі розмови також можуть виявляти слабкості. Просте «Відносно!» недостатньо. Розгляньте: « Виправлено помилку # 123 оновленням логіки [компоненту]. Додано тест регресії. » Цей параметр надає контекст і демонструє активне спілкування. Крім того, пам’ ятайте про те, щоб просити про допомогу; чітке формулювання ваших питань є найважливішим. Замість того, щоб висловити: «Це не працює», спробуйте: «Я стикаюся з проблемою з [спеціфічною функціональністю]. Я переглянув відповідну документацію і спробував зневаджувати за допомогою [tools], але не зміг розв’ язати проблему. Чи може хтось надати вам деякі рекомендації?» Продемонструвавши, що ви вже зробили певні зусилля, ви зменшите розчарування і отримаєте корисні відповіді.
Нарешті, пам’ятайте, що активне слухання і ретельна реакція так само важливі, як і початкове спілкування. Не бійтеся просити про пояснення, якщо щось не ясно - запитання “Чи можете ви розібратися, що ви маєте на увазі під “виробничим в’язким місцем”?” є цілком прийнятним. Збудування репутації, заснованої на ясному, шанобливому і конструктивному спілкуванні, значно підвищить ваш внесок та інтеграцію у спільноту з відкритим кодом.