Кава-брейк #100. Як запустити проект із відкритим вихідним кодом на GitHub

Джерело: FreeCodeCamp Розробники всього світу використовують GitHub, щоб ділитися своїми проектами. У цій статті я спробую дати кілька порад, які допоможуть вам створити чудовий проект із відкритим вихідним кодом. Ви також можете використати ці поради для створення хакатонних проектів. Нещодавно я опинився на бажаній сторінці GitHub Trending. Я був другим трендовим розробником на всьому GitHub, а також у розділі Python, що стало для мене дуже приємним сюрпризом. Мене також згадали у щоденному інформаційному бюлетені GitHub після того, як я переклав один із моїх проектів у open source. Якщо цікаво, ви можете переглянути мій репозиторій тут .

Знайдіть свою мотивацію

Намагатися потрапити до розділу GitHub Trending практично неможливо. Під час визначення трендів у GitHub використовуються набагато складніші алгоритми, ніж просто кількість зірок. Щоб потрапити до трендів, вам потрібна сильна мотивація. Що ж, спершу ви можете брати участь у хакатонах, створювати проекти та експериментувати з іншими проектами. І незабаром ви знайдете щось, що можна було б перетворити на бібліотеку або зробити утилітою, і таке інше. Ваша мотивація для створення проекту може виходити звідки завгодно. Наприклад, я щодня вивчаю нові статті з машинного навчання на arXiv(архів статей з відкритим доступом) та читаю ті, які мені цікаві. Одна стаття, яку я прочитав, спонукала мене створити власний Python package. Іншим разом я був на хакатоні з навчання моделі машинного навчання і захотів взяти участь у чомусь подібному. Потім наша команда вирішила створити ще один проект із відкритим вихідним кодом під назвою TF-Watcher. Як бачите, завжди можна знайти будь-які проблеми, над якими можна попрацювати, коли ви шукаєте мету для свого проекту. Зверніть увагу — коли я кажу, що у вас має бути сильна мотивація, я не маю на увазі, що проект має бути справді величезним чи дуже складним. Це може бути простий проект, який полегшує життя розробників. Подумайте про це так: якби був проект, подібний до того, який ви хочете розробити, Ви б його самі використали? Якщо відповідь позитивна, то у вас достатньо мотивації для створення проекту, незалежно від його розміру та складності. Нещодавно один хлопець з Окленда, штат Каліфорнія, порушив веб-розробку по всьому світу,видаливши всього 11 рядків коду . Можливо, ви чули про left-pad - дуже маленький пакет npm з відкритим вихідним кодом, що містить всього 11 рядків. Але виявляється, його використовували безліч розробників у всьому світі.

Вивчіть свою ідею

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

Чи існує вже подібний проект чи інструмент?

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

Якщо щось подібне справді існує, чи може ваш проект покращити його?

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

Чи можете ви пояснити свій проект, ніби мені 5 років?

Пояснити суть свого проекту так, ніби вашому співрозмовнику п'ять років, — чудова вправа, яку я люблю виконувати, як тільки у мене з'являється ідея для репозиторію. Я намагаюся розповісти, яку мету прагне досягти проект, як він працює чи чому він кращий за аналогічні репозиторії, своєму другу, який не дуже розуміється на предметі. Це допомагає мені розвиватися або отримати чітке уявлення про те, чим хочу займатися у своїх проектах. Спроби пояснити проект другові часто також допомагають мені виявити недоліки в моєму плані чи припущеннях, які я міг зробити, розмірковуючи про проект. Цей процес допомагає мені тоді, коли я починаю фазу розробки проекту на дошці. Для цього можна використовувати GitHub або Trello, JetBrains Spaces і таке інше.

Що ви можете дізнатися з найкращих репозиторіїв у аналогічних категоріях?

Ви часто можете черпати натхнення та навчатися у репозиторіїв, що належать до аналогічних категорій. Подивіться, як написано та структуровано їх код. У моєму випадку мені дуже сподобалося, як написано reformer-pytorch . Його легко використовувати у ваших проектах як бібліотека Python.

Як розробити репозиторій вашого проекту

Можливо, ви чули популярну цитату Мартіна Фаулера: “Будь-який дурень може написати код, зрозумілий комп'ютеру. Хороші програмісти пишуть код, зрозумілий людям”. Якщо люди не можуть зрозуміти ваш код, вони не використовуватимуть його. У своїх репозиторіях я помітив, що коли я витрачаю більше часу на те, щоб зробити речі простими та зручними у використанні, ці проекти зрештою стають більш популярними. Тож постарайтеся витратити додатковий час на те, щоб зробити свій проект більш зручним та інтуїтивно зрозумілим. Як правило, при розробці репозиторію:

• Ви повинні додати ліцензію з відкритим кодом. Вона дозволяє людям використовувати, копіювати, змінювати та робити свій внесок у ваш проект, зберігаючи при цьому авторські права. Ви можете легко знайти ліцензію для вашого проекту на Choosealicense.com .

• Напишіть хороший README: це буде цілий розділ, тому що він дуже важливий.

• Використовуйте узгоджені угоди про код та чіткі імена функцій/методів/змінних. Часто можна використовувати якийсь інструмент статичного аналізу коду, наприклад black , ktlint та інші.

• Переконайтеся, що код чітко прокоментований, задокументуйте свої думки і позначте можливі проблеми.

• Переконайтеся, що в історії змін, проблем або pull requests немає конфіденційних матеріалів (наприклад, ключів API, паролів або іншої закритої інформації).

• Якщо ви розробляєте додаток/бібліотеку, я б порекомендував вам використовувати GitHub releases. Намагайтеся вести чіткі примітки до випуску та журнали змін щоразу, коли ви робите новий реліз, щоб співтовариство могло відстежувати, що у ньому нового. Запишіть, які помилки було виправлено, і так далі.

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

Як написати хороший README

Хороший README, безперечно, є одним із найважливіших компонентів репозиторію. Потенційні учасники зазвичай спочатку перевіряють README, і лише потім, якщо це цікаво, вони дивляться на код чи розглядають можливість використання проекту. У мене немає універсального посібника з написання README. Просто поекспериментуйте з тим, що підходить для вашого проекту. Напевно, ви захочете включити до свого README ці компоненти:

Поясніть, що робить проект

Намагайтеся описати проект всього в 3-4 рядки. Не турбуйтеся про увімкнення занадто великої кількості дрібних деталей або функцій — ви можете додати їх у наступних розділах. Це перше, що читають відвідувачі вашого репозиторію, тому постарайтеся зробити його цікавим.

Створіть чудове зображення обкладинки або логотипу проекту

Якщо ви маєте логотип або обкладинку для вашого проекту, вкажіть його.

Розмістіть графічні ярлики з метаданими

Ви бачите маленькі значки у верхній частині README, які передають метадані, наприклад, чи пройшли всі тести для проекту. Ви можете використовувати shields.io , щоб додати їх до README. Вони можуть підвищити довіру до вашого проекту, причому відвідувачам не потрібно переглядати весь ваш код.

Додати візуальні ефекти

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

Поясніть, як встановити чи налаштувати свій проект

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

Наведіть чіткі приклади використання

Я думаю, що це дуже важливо мати у README. Не варто очікувати, що інші розробники довго читатимуть ваш код — зробіть усе якомога простіше для них. Завжди перевіряйте та перевіряйте, що ваші приклади коду або розділ “How To” легко відтворюються. Крім того, переконайтеся, що він зрозумілий широкому колу користувачів, і не забудьте додати інструкції щодо його запуску. Оскільки мій проект являє собою пакет Python, я створив блокнот Colab Notebook, що додається, щоб продемонструвати використання цього пакета. Це дозволяє людям легко випробувати його у своїх браузерах, не встановлюючи нічого на власні машини. Є досить багато продуктів, які дозволяють це робити, наприклад, repl.it, Glitch, Codepen і таке інше.

Поясніть, де можна застосувати цей проект

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

Розкажіть, як люди можуть отримати допомогу або зробити свій внесок у проект

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

Зовнішня документація

Припустимо, ви думаєте, що ваш README надто довгий. У цьому випадку ви можете створити додатковий веб-сайт документації та зробити посилання на нього в README, не пропускаючи будь-якої важливої ​​інформації. Оскільки я багато працюю з Python, зазвичай використовую Sphinx для створення документації з рядків документації Python. Я вважаю Sphinx досить гнучким та простим у налаштуванні. Існує досить багато варіантів створення документації: mkdocs , Docsaurus , docsifyта інші. Однак для мого проекту, який почав набирати обертів, мені не знадобився зовнішній веб-сайт із документацією. Ось приклад того, що, на мою думку, могло б стати хорошим початком README з одного з моїх власних проектів. Це не повний README, а те, що помістилося на одній картинці: Нарешті, для більшого натхнення я пропоную вам спробувати використати керівництво “ Make a README ”.

Як залучити відвідувачів на вашу сторінку GitHub

Після того, як ви створабо красивий README та зробабо проект загальнодоступним, вам потрібно подумати про залучення людей на сторінку GitHub. По-перше, переконайтеся, що ви додали відповідні теги до репозиторію GitHub. Ці теги значно спростять виявлення проекту людьми, які вивчають GitHub.

Поділіться своїм проектом у Hacker News, Twitter та Reddit

Відмінні місця для публікації про ваш проект – Hacker News та Reddit. Але майте на увазі, що домогтися того, щоб ваш пост став головною новиною або топ-постом на будь-якій із цих платформ, — складне завдання. Коли один із моїх репозиторіїв став топ-історією, він отримав понад сотню зірок за пару годин. Але коли я спочатку розмістив своє репо на Hacker News, у мене не було жодного голосу. Тільки коли хтось із спільноти помітив мій проект і опублікував його у Hacker News, він став головною новиною. Тому часто потрібно хороше планування та невелика допомога з боку друзів, щоб вивести ваш проект на вершину. У моєму випадку Twitter був справді чудовим місцем, щоб залучити найперших відвідувачів мого проекту та вийти на зовнішню аудиторію. Це часто служить чудовим способом, що дозволяє людям швидко зрозуміти, чи можуть вони зацікавитись вашим проектом. І у вас просто є обмежена кількість персонажів, щоб продавати свій репозиторій людям. Крім того, не перестарайтеся з публікаціями про свій проект на будь-якій платформі, тому що він може бути помічений як спам.

Відгуки мають значення, але не так, як ви вважаєте

Я часто отримую повідомлення електронної пошти або повідомлення з відгуками на свій проект або книгу. Але я впевнений, що в цьому немає великого сенсу. Якщо ви хочете, щоб хтось залишив відгук про ваш проект, то спочатку досягайте, щоб вони використали ваш проект і визнали його корисним. Також додайте кнопку “tweet this project” у README. Тоді люди, яким подобається проект, природно почнуть його поширювати серед своєї аудиторії. Також майте на увазі, що відгуки не приносять вам зірок. Люди відзначатимуть ваш проект зіркою лише в тому випадку, якщо він їм сподобається. Це, безумовно, не означає, що ви не повинні просити людей про допомогу, зворотний зв'язок або перевірку коду. Насправді ви завжди повинні намагатися реагувати на всі види відгуків: поліпшення, помилки, невідповідності і так далі. Завжди будьте готові прийняти негативні відгуки та подумати про те, як ви можете покращити їх. Можливо, ви дізнаєтесь кілька нових речей :) У моєму випадку я помітив надзвичайно велику кількість відвідувачів, які приходять на проект із Twitter. Мій проект був реалізований за допомогою TensorFlow та Keras, і через пару днів я виявив, що сам творець Keras обговорює мій проект! Швидше за все це сталося через те, що я додав “Твітнути про цей проект” у верхній частині README і дозволив його поширити в соцмережах.

Поради спільноти розробників щодо створення проекту на GitHub

Як цікава вправа я попросив спільноту в Twitter дати будь-які поради, які я міг би включити до цього блогу. Ось кілька із них:

• (Ви маєте додати) 1. Документацію 2. Журнали рішень

• Гарні шаблони випуску та PR. Ви також можете використати форми випуску GitHub.

• Документація (має бути повною та) включати архітектуру додатка, упаковку, посібник зі стилю, обговорення коду, посилання на бібліотеку технологічної платформи, що використовується, необхідні токени і так далі.

Висновок

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