Як правильно внести свій внесок в Open Source проект прості підказки, SavePearlHarbor

Ще одна копія хабора

Головне меню

Навігація за записами

Як правильно внести свій внесок у Open Source проект: прості підказки

Open Source проекти з кожним днем набирають все більших обертів, з'являються нові, активно розвиваються популярні. Такі проекти як Bootstrap, Angular.js, Elasticsearch, Symfony Framework, Swift та багато інших залучають нових розробників, їхня спільнота зростає. Все це дає величезне зростання проектам, а самим розробникам цікаво взяти участь у розробці чогось, чим користується весь світ.

Я, як і багато інших програмістів, не встояв і час від часу беру участь у розробці Open Source проектів, в основному на PHP. Але коли я починав, я зіткнувся з проблемою — я не знав, як правильно організувати процес «контриб'ютингу», з чого почати, як зробити так, щоби мій Pull Request розглянули і т.д.

Всім початківцям «контриб'ютерам», які зіткнулися зі схожими проблемами, ласкаво просимо під кат.

Сам процес участі в Open-Source проекті розглянемо на прикладах різних PHP фреймоворків, візьмемо Symfony, Yii2.

Далі слідознайомитися з правилами участі у розробцідля обраного Вами проекту. Ці правила зазвичай знаходяться у файлі

докорінно репозиторія. Для Symfony, наприклад, це Symfony Contributing.

Зазвичай, є кілька способів участі в розробці Open Source проекту, основні - це відправка повідомлення про якусь помилку або бажане поліпшення (Submitting Issue) або безпосереднє створення Pull Request з вашим виправленням або покращенням (Code Contributing). Так само Ви можете взяти участь у покращенні документації, відповідях на питання, що виникли в інших розробників і багато іншого.

Надсилання Issue

Якщо Ви захотіли повідомити розробників про будь-яку знайдену помилку або покращення, Вам необхідно створити відповідний GitHub Issue. Але перед тим, як створювати його, перевірте, чи не існує вже такого ж чи схожого, створеного будь-ким іншим. Перед створенням також не забудьте ознайомитися з правилами надсилання звіту про помилку для цього проекту. Наприклад, правила для Yii Framework Зазвичай, опис має бути максимально чітким, зрозумілим, бажано наявність прикладів і описи як відтворити помилку. Це заощадить величезний час і розробникам, і Вам, оскільки позбавить Вас відповіді на уточнюючі питання і т.д.

Надсилання Pull Request

Якщо ви знайшли GitHub Issue, яке хотіли б виправити або створили свій власний, то наступним Вашим кроком буде відправка відповідного Pull Request. Знову ж таки, для початку не забудьте ознайомитися з правилами участі в розробці для обраного Вами проекту. Наприклад, ось правила для Yii.

Далі я хотів би описати найбільш часто зустрічається процес роботи з Git і GitHub за участю в Open Source проектах (Git Workflow). Цей процес може відрізнятися від проекту до проекту, та й загалом він притаманний не тільки Open Source проектам, а й багатьом закритим проектам на GitHub та BitBucket.

Крок 1 - Підготовка робочого оточення

Звичайно, для розробки Вам потрібно підготувати Ваше робоче оточення. Багато Open Source проектів вказує, як саме необхідно його налаштувати, які бібліотеки, пакети, інструменти, їх версії тощо необхідні.

Для PHP-проектів зазвичай Вам знадобиться приблизно такий мінімальний список

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

Крок 2 - Створюємо копію (Fork) репозиторія проекту

Заходимо на сторінку обраного Вами проекту та натискаємо кнопку «Fork». Ця команда створить Вашу власну копію репозиторію цього проекту.

Далі Вам необхідно схиляти копію репозиторію.

Далі Вам необхідно додати гілку upstream для проекту, яка посилатиметься на базовий репозиторій (варіант для Yii)

Крок 3 - Налаштуємо Git

Далі, необхідно зробити невелике налаштування Вашого Git, щоб під час відправлення коммітів відображалося ваше коректне ім'я. Для цього достатньо виконати дані команди:

Якщо ви хочете налаштувати дані значення локально для даного проекту, у папці проекту виконайте

Крок 4 - Composer

Далі, у 99% випадків для проекту Вам доведеться виконати завантаження бібліотек через Composer

Крок 5 - Тести

Перед тим, як розпочати роботу, налаштуйте у своїй улюбленій IDE або просто в консолі PHPUnit (рідше Behat, PhpSpec тощо) для запуску та роботи з тестами. Після налаштування запустіть тести для проекту та перевірте, чи вони коректно проходять.

Крок 6 - Працюємо з кодом

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

Вибирайте чітко та лаконічно ім'я гілки, яке відображало б суть змін. Вважається гарною практикою включати в назві гілки номер GitHub issue.

Тепер ви можете сміливо розпочинати роботу над кодом. Працюючи, пам'ятайте про такі правила:

Дотримуйтесьстандарти кодування (зазвичай це PSR-стандарти);
Пишіть юніт-тести, щоб довести, що помилку виправлено, або що нова функція насправді працює;
Намагайтеся не порушувати зворотну сумісність без нагальної потреби;
Використовуйте прості та логічно цілісні комміти;
Пишіть чіткі, ясні, повні повідомлення під час зміни змін.

Крок 7 - Надсилаємо Pull Request

Поки Ви працювали над кодом, до основної галузі проекту могли бути внесені інші зміни. Тому перед відправкою ваших змін Вам необхідно зробити rebase Вашої гілки. Робиться це так:

Тепер ви можете надіслати Ваші зміни.

Після цього заходимо у Ваш репозиторій-клон проекту, в якому Ви берете участь і натискаємо кнопку New Pull Request. І бачимо таку форму:

Ліворуч необхідно вибрати гілку, в яку Ви хочете смержити зміни (зазвичай це master, а взагалі це гілка, на яку ви робили rebase). Дело — гілку з Вашими змінами. Далі Ви побачите повідомлення від GitHub про те, чи можливо автоматично смертіти зміни чи ні. У більшості випадків Ви побачите Able to merge. Якщо є конфлікти, Вам швидше за все доведеться переглянути Ваші зміни.

Далі натискаємо кнопку Create Pull Request. При заповненні імені та опису вашого Pull Request вважається гарною практикою вказувати номер Issue, для якого створено ваш Pull Request.

Зазвичай для багатьох великих проектів налаштований сервер CI, часто Travis-CI. Після створення Pull Request він проганятиме тести, можливо якісь інструменти для метрик і так далі. Результати його роботи ви побачите у Вашому Pull Request як показано нижче:

Якщо тести не будуть пройдені або білд не буде зібраний, випобачите червоне повідомлення про помилку і за посиланням Details зможете побачити, що саме не так. У більшості випадків Вам необхідно буде виправити ваш Pull Request, щоб усі перевірки проходили успішно.

Крок 8 - Переробляємо Pull Request

Якщо з Pull Request все добре, то незабаром він буде смержений кимось із команди. Але часто буває, що розробники попросять Вас внести якісь зміни.

Для цього просто повертаємось до кроку 6 і після внесення змін та комміту виконуємо схожі команди:

Примітка:Особисто я люблю відправляти Pull Request лише з 1 коммітом. Для цього я роблю squash непотрібних коммітів. Як це зробити можна прочитати тут - gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html

Крок 9 - Забираємось після себе

Після того, як ваш Pull Request був прийнятий або відкинутий, Вам необхідно видалити гілку зі змінами. Робиться це просто

Замість останньої команди такде можна виконати

Висновок

Мабуть, це все, що стосується базових речей участі в Open Source проектах. Хотів би додати, щоб Ви не лінувалися і брали участь в Open Source проектах, це величезний та цікавий досвід, а також галочка у резюме 😉