JavaRush /Java блог /Random /Кофе-брейк #100. Как запустить проект с открытым исходным...

Кофе-брейк #100. Как запустить проект с открытым исходным кодом на GitHub

Статья из группы Random
Источник: FreeCodeCamp Разработчики всего мира используют GitHub, чтобы делиться своими проектами. В этой статье я попытаюсь дать несколько советов, которые помогут вам создать отличный проект с открытым исходным кодом. Вы также можете использовать эти советы для создания хакатонных проектов. Совсем недавно я оказался на желанной странице GitHub Trending. Я был вторым трендовым разработчиком на всем GitHub, а также в разделе Python, что стало для меня очень приятным сюрпризом. Меня также упомянули в ежедневном информационном бюллетене GitHub после того, как я перевел один из моих проектов в open source. Если интересно, вы можете посмотреть мой репозиторий здесь. Кофе-брейк #100. Как запустить проект с открытым исходным кодом на GitHub - 1

Найдите свою мотивацию

Пытаться попасть в раздел GitHub Trending практически невозможно. Во время определения трендов в GitHub используются гораздо более сложные алгоритмы, чем просто количество звезд. Чтобы попасть в тренды, вам нужна сильная мотивация. Что ж, для начала вы можете участвовать в хакатонах, создавать проекты и экспериментировать с другими проектами. И вскоре вы найдете что-то, что можно было бы превратить в библиотеку или сделать утилитой, и так далее. Ваша мотивация для создания проекта может исходить откуда угодно. Например, я ежедневно изучаю новые статьи по машинному обучению на arXiv (архив статей с открытым доступом) и читаю те, которые мне интересны. Одна статья, которую я прочитал, побудила меня создать собственный Python package. В другой раз я был на хакатоне по обучению модели машинного обучения и захотел поучаствовать в чем-то подобном. Затем наша команда решила создать еще один проект с открытым исходным кодом под названием TF-Watcher. Как видите, всегда можно найти какие-либо проблемы, над которыми можно поработать, когда вы ищете цель для своего проекта. Обратите внимание — когда я говорю, что у вас должна быть сильная мотивация, я не имею в виду, что проект должен быть действительно огромным или очень сложным. Это может быть вполне простой проект, который облегчает жизнь разработчиков. Подумайте об этом так: если бы был проект, подобный тому, который вы хотите разработать, вы бы его сами использовали? Если ответ положительный, то у вас достаточно мотивации для создания проекта, независимо от его размера и сложности. Не так давно один парень из Окленда, штат Калифорния, нарушил веб-разработку по всему миру, удалив всего 11 строк кода. Возможно, вы слышали о left-pad — очень маленьком пакете npm с открытым исходным кодом, содержащем всего 11 строк. Но оказывается, его использовали множество разработчиков по всему миру.

Изучите свою идею

Как только вы найдете проблему и у вас появится достаточно мотивации, чтобы начать работать над ней, то, скорее всего, вам захочется потратить немало времени на свое исследование. Но перед этим попытайтесь ответить на несколько вопросов:

Существует ли уже подобный проект или инструмент?

Если аналога еще нет и в нем есть необходимость, тогда приступайте к созданию. Если что-то подобное существует, хорошо разработано и активно используется, возможно, вам стоит поискать другую идею. На GitHub есть огромное количество проектов с открытым исходным кодом, и довольно часто там можно найти репозиторий, выполняющий аналогичные задачи (более распространенные, чем вы думаете). Но вы все равно можете работать над своим проектом и улучшать его.

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

Если аналог уже есть, вы можете сделать его более модульным или более эффективным. Вы можете попробовать реализовать его на другом языке или улучшить другими способами. Отличный способ — взглянуть на проблемы в этом репозитории. Попробуйте провести исследование с помощью существующих решений (если они есть) и выясните, какой элемент проекта можно улучшить. В моем случае я черпал вдохновение из прочитанной интересной исследовательской статьи (Fastformer: Additive Attention Can Be All You Need). Я также обнаружил официальную реализацию кода и реализацию документа сообществом в PyTorch. В конце концов, мой репозиторий, хотя и являлся производным от исследовательских работ, сильно отличался от существующих реализаций кода.

Вы можете объяснить свой проект, как будто мне 5 лет?

Объяснить суть своего проекта так, как будто вашему собеседнику пять лет, — отличное упражнение, которое я люблю выполнять, как только у меня появляется идея для репозитория. Я пытаюсь рассказать, какую цель стремится достичь проект, как он работает или почему он лучше аналогичных репозиториев, своему другу, который не очень разбирается в предмете. Это помогает мне развиваться или получить четкое представление о том, чем я хочу заниматься в своих проектах. Попытки объяснить проект другу часто также помогают мне обнаружить недостатки в моем плане или предположениях, которые я мог сделать, размышляя о проекте. Этот процесс помогает мне также тогда, когда я начинаю фазу разработки проекта на доске. Для этого можно использовать GitHub или Trello, JetBrains Spaces и так далее. Мне нравится использовать на этом этапе контрольные списки проектов и проблем GitHub, чтобы помочь мне управлять, расставлять приоритеты и иметь четкое общее представление о том, что нужно делать.

Что вы можете узнать из лучших репозиториев в аналогичных категориях?

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

Как разработать репозиторий вашего проекта

Возможно, вы слышали популярную цитату Мартина Фаулера: “Любой дурак может написать код, понятный компьютеру. Хорошие программисты пишут код, понятный людям”. Если люди не могут понять ваш код, они не будут его использовать. В своих репозиториях я заметил, что, когда я трачу больше времени на то, чтобы сделать вещи простыми и удобными в использовании, эти проекты в конечном итоге становятся более популярными. Так что постарайтесь потратить дополнительное время на то, чтобы сделать свой проект более удобным и интуитивно понятным. Как правило, при разработке репозитория:
  • Вы должны добавить лицензию с открытым исходным кодом. Она позволяет людям использовать, копировать, изменять и вносить свой вклад в ваш проект, сохраняя при этом авторские права. Вы можете легко найти лицензию, подходящую для вашего проекта, на Choosealicense.com.

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

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

  • Убедитесь, что ваш код четко прокомментирован, задокументируйте свои мысли и обозначьте возможные проблемы.

  • Убедитесь, что в истории изменений, проблемах или pull requests нет конфиденциальных материалов (например, ключей API, паролей или другой закрытой информации).

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

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

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

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

Объясните, что делает проект

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

Создайте отличное изображение обложки или логотипа проекта

Если у вас есть логотип или обложка для вашего проекта, укажите его.

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

Кофе-брейк #100. Как запустить проект с открытым исходным кодом на GitHub - 2Вы видите маленькие значки в верхней части README, которые передают метаданные, например, прошли ли все тесты для проекта. Вы можете использовать shields.io, чтобы добавить их в README. Они могут повысить доверие к вашему проекту, при этом посетителям не нужно просматривать весь ваш код.

Добавьте визуальные эффекты

Вы всегда должны стараться включать визуальные элементы в свой README. Это может быть гифка, показывающая ваш проект в действии, или скриншот вашего проекта. Хорошая графика в README действительно может помочь убедить других разработчиков использовать ваш проект.

Объясните, как установить или настроить свой проект

Вы также должны включить конкретные инструкции по установке. Включите все необходимые зависимости и все остальное, что нужно установить другим разработчикам, чтобы использовать ваш проект. Если вы столкнулись с какими-либо проблемами при настройке проекта или установке зависимости, вполне вероятно, что пользователи тоже столкнутся с этим, поэтому убедитесь, что вы рассказали об этом. Это может быть очень просто: Кофе-брейк #100. Как запустить проект с открытым исходным кодом на GitHub - 3

Приведите четкие примеры использования

Я думаю, что это очень важно иметь в README. Не стоит ожидать, что другие разработчики будут долго читать ваш код — сделайте все как можно проще для них. Всегда проверяйте и перепроверяйте, что ваши примеры кода или раздел “How To” легко воспроизводимы. Кроме того, убедитесь, что он понятен широкому кругу пользователей, и не забудьте добавить инструкции по его запуску. Поскольку мой проект представляет собой пакет Python, я создал прилагаемый блокнот Colab Notebook, чтобы продемонстрировать использование этого пакета. Это позволяет людям легко опробовать его в своих браузерах, не устанавливая ничего на свои собственные машины. Есть довольно много продуктов, которые позволяют это делать, например, repl.it, Glitch, Codepen и так далее.

Объясните, где можно применить этот проект

Часто бывает полезно перечислить особенности вашего проекта и проблемы, которые он может решить. Вам не нужно описывать все функции, над которыми вы работали, но поделитесь основными из них. Это поможет разработчикам понять, на что способен ваш проект и почему им следует его использовать.

Расскажите, как люди могут получить помощь или внести свой вклад в проект

Наконец, вы должны четко указать, готовы ли утверждать коммиты и каковы ваши требования для их принятия. Вам также следует задокументировать команды для линтинга кода или запуска тестов. Эти этапы помогают обеспечить высокое качество кода и снизить вероятность того, что изменения случайно что-то сломают.

Внешняя документация

Предположим, вы думаете, что ваш README слишком длинный. В этом случае вы можете создать дополнительный веб-сайт документации и сделать ссылку на него в README, не пропуская какую-либо важную информацию. Поскольку я много работаю с Python, я обычно использую Sphinx для создания документации из строк документации Python. Я считаю Sphinx достаточно гибким и простым в настройке. Существует довольно много вариантов создания документации: mkdocs, Docsaurus, docsify и другие. Однако для моего проекта, который начал набирать обороты, мне не понадобился внешний веб-сайт с документацией. Вот пример того, что, как мне кажется, могло бы стать хорошим началом README из одного из моих собственных проектов. Это не полный README, а то, что поместилось на одной картинке: Кофе-брейк #100. Как запустить проект с открытым исходным кодом на GitHub - 4Наконец, для большего вдохновения я предлагаю вам попробовать использовать руководство “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.

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

Заключение

Спасибо, что прочитали до конца. Я надеюсь, что это поможет вам в создании своих собственных проектов с открытым исходным кодом. Используя эти советы и экспериментируя, а также приложив усилия, вы можете создать отличный проект.
Комментарии
ЧТОБЫ ПОСМОТРЕТЬ ВСЕ КОММЕНТАРИИ ИЛИ ОСТАВИТЬ КОММЕНТАРИЙ,
ПЕРЕЙДИТЕ В ПОЛНУЮ ВЕРСИЮ