Ръководство за принос към open source

Софтуерът с отворен код задвижва съвременния уеб, а приносът обратно към него е едно от най-удовлетворяващите неща, които един разработчик може да направи. Независимо дали поправяте печатна грешка в документацията, или реализирате голяма функционалност, всеки принос има значение.

Това ръководство обхваща практическата страна: избор на проект, запознаване с него, преди да пишете код, подготовка на pull request, който лесно се приема, и справяне с прегледа.

Как да намерите подходящия проект

Започнете с инструментите, които вече използвате. Ще имате контекст за проблемната област и истинска мотивация да подобрите нещо, което засяга ежедневната ви работа. Търсете хранилища с файл CONTRIBUTING.md, активни тракери за проблеми и поддържащи, които отговарят на проблемите в разумен срок.

Подходящите първи задачи често са отбелязани с етикети като „good first issue“, „help wanted“ или „beginner friendly“. Тези задачи са специално подбрани за новодошли и обикновено съдържат допълнителен контекст, който да ви помогне да започнете.

Няколко бързи сигнала показват дали един проект е добро място, където да вложите времето си:

• Скоро слети pull request-и от хора извън основния екип. Това показва, че външните приноси наистина се приемат.
• Ясен лиценз във файл LICENSE. Без него нямате определено право да използвате или променяте кода.
• Кодекс на поведение и уважителен тон в дискусиите по проблемите.
• Работещ набор от тестове, който можете да изпълните локално. Много по-лесно е да променяте кода безопасно, когато можете да го проверите.

Прочетете, преди да пишете

Преди да докоснете кода, отделете време за собствената документация на проекта. CONTRIBUTING.md обикновено отговаря на въпросите, които поддържащите са уморени да повтарят: как да настроите средата за разработка, към кой клон да насочите промените, как трябва да се форматират къмитите и дали трябва да подпишете Contributor License Agreement или да добавите подпис Developer Certificate of Origin към къмитите си.

След това прочетете проблема, по който искате да работите, включително всеки коментар. Възможно е вече да има предложен подход, отхвърлен подход или някой друг да работи по него. Ако промяната е нещо повече от малка поправка, оставете коментар с описание на това, което смятате да направите, и изчакайте някой от поддържащите да се съгласи. Десет минути дискусия могат да ви спестят уикенд, прекаран в pull request, който не отговаря на посоката на проекта.

Настройване на вашия fork

Направете fork на хранилището и създайте клон за функционалността с описателно име. Запазете препратка към оригиналното хранилище, за да можете да сте в крак с него:

git clone https://github.com/<your-username>/<project>.git
cd <project>
git remote add upstream https://github.com/<owner>/<project>.git
git switch -c fix/date-parsing-timezone

Изпълнете командите за инсталиране, компилиране и тестване на проекта, преди да промените каквото и да било. Ако тестовете се провалят при чисто копие, искате да го знаете сега, а не след като сте направили промени и се чудите дали не сте счупили нещо.

Когато основният клон се придвижи напред, докато работите, актуализирайте своя клон:

git fetch upstream
git rebase upstream/main

Някои проекти предпочитат merge пред rebase; следвайте това, което пише в CONTRIBUTING.md.

Вашият първи принос

Напишете кода си, като спазвате стандартите за код на проекта и включвате тестове, където е приложимо. Поддържайте промените си фокусирани — pull request, който решава един проблем, се преглежда много по-лесно от такъв, който се захваща с пет.

Фокусът означава и да устоите на изкушението да разчиствате наоколо. Ако забележите непоследователно форматиране или функция, която бихте написали по друг начин, оставете ги или отворете отделен pull request. Несвързаните промени правят разликите по-трудни за четене, а прегледа — по-бавен.

При поправките на грешки най-убедителното, което можете да включите, е тест, който се проваля преди промяната ви и минава след нея. Той доказва, че грешката е съществувала, показва, че поправката ви я отстранява, и не ѝ позволява да се върне.

Правете и къмитите си четими. Доброто съобщение към къмит има кратък обобщаващ ред в повелително наклонение и, когато помага, тяло, което обяснява защо е била нужна промяната:

Fix timezone offset when parsing ISO dates

Dates without an explicit offset were parsed as UTC, which shifted
event times for users in other zones. Parse them as local time to
match the documented behaviour.

Изпълнете линтера и форматера на проекта, преди да качите промените. Много проекти проверяват това автоматично, а неуспешната проверка е лесна причина рецензентът да остави pull request-а ви настрана.

Как да напишете добър pull request

Напишете ясно описание на pull request-а, което обяснява проблема, вашето решение и компромисите, които сте обмислили. Поставете връзка към съответния проблем. Ако промяната ви засяга потребителския интерфейс, добавете екранни снимки.

Структура, която работи за повечето промени:

1. Какъв проблем решава това? Едно-две изречения с връзка към проблема.
2. Какво променихте? Кратко обобщение на подхода, особено на всичко, което не е очевидно.
3. Как го тествахте? Командите, които сте изпълнили, и всички ръчни стъпки, които рецензентът може да повтори.
4. Какво остава отворено? Известни ограничения или последваща работа, която сте решили да не включвате.

Ако проектът има шаблон за pull request, попълнете всеки раздел. Отварянето на чернова на pull request е добър начин да получите ранна обратна връзка за посоката, преди да изпипате детайлите.

Етикет при преглед на кода

Бъдете търпеливи с поддържащите. Те често отделят времето си доброволно. Отговаряйте любезно на обратната връзка от прегледа, задавайте уточняващи въпроси, когато коментарите не са ясни, и правете исканите промени своевременно. Ако някой от поддържащите предложи различен подход, опитайте се да разберете мотивите му, преди да възразите.

Някои навици правят прегледа по-гладък:

• Отговаряйте на всеки коментар, дори с кратко „готово“, за да знае рецензентът, че сте го видели.
• Качвайте последващи къмити, вместо да правите force-push по време на прегледа, освен ако проектът не изисква друго. Така рецензентите виждат само това, което се е променило от последния им преглед.
• Не го приемайте лично. Рецензентите оценяват промяната, а не вас, и те ще поддържат този код дълго след като pull request-ът ви бъде слят.
• Напомнете учтиво, ако минат седмица-две без отговор. Един кратък коментар е напълно приемлив; многократните напомняния не са.

Понякога отговорът е „не“. Проектът може да откаже промяна, защото тя не се вписва в пътната карта или би добавила тежест по поддръжката. Това е легитимен изход и начинът, по който реагирате, определя как ще бъде приет следващият ви принос.

Отвъд кода

Приносите не се ограничават до код. Подобренията в документацията, докладите за грешки с ясни стъпки за възпроизвеждане, дизайнерските материали и подкрепата за общността в дискусиите по проблемите са все ценни начини да допринесете.

Добрият доклад за грешка е принос сам по себе си. Посочете версията, която използвате, средата си, точните стъпки за възпроизвеждане, какво сте очаквали и какво се е случило вместо това. Минималното възпроизвеждане, например малко хранилище или кратък фрагмент код, който показва проблема в изолация, често помага за поправянето на грешката повече от всичко друго.

Продължавайте

Общността на отворения код процъфтява, когато хората дават обратно. Започнете с малко, усвоете основите и постепенно поемайте по-големи предизвикателства. Всеки слят pull request ви учи на повече за кодовата база и изгражда доверие с поддържащите ѝ, а именно това доверие с времето се превръща в по-големи задачи. Приносът ви е добре дошъл.