Полный гайд по OpenSource на GitHub

Стартануть свой OSS может быть очень сложно. Не ясно, с чего начать, как он вообще должен выглядеть, как его продвигать. Тут очень помогает насмотренность – ходишь по крупным GitHub репозиториям и делаешь "как у них". Но я избавил вас от такой необходимости и подготовил чек-лист оформления репозитория для старта вашего проекта на GH😎

Основная цель всего этого оформления – сделать репозиторий максимально привлекательным для мимопроходящих людей (чтобы конвертить их в пользователей) и максимально гостеприимным для контрибуторов. Чем раньше вы позаботитесь о своем инструментарии - тем вероятнее в ваш проект будут коммитить другие люди.

1️⃣ README.md - папа и мама вашего проекта. Он должен быть даже раньше кода. Именно по нему юзеры принимают решение – юзать или не юзать. Там обязательно должны быть следующие секции:
– основная идея проекта. 1-3 предложения. Ильяхов в помощь
– основные фичи буллет-поинтами
– как проект установить
– базовый пример использования (код / скрины / что угодно в зависимости от проекта)
– как запускать
– подсветить другие важные фичи
– из прикольного можно добавить аватарки всех контрибуторов, людям будет приятно увидеть себя в списке (пример из репы FS)

2️⃣ Заполнить раздел "Описание" вашего проекта (правый верхний угол репозитория) - именно это описание будет отображаться на превью карточки репозитория по ссылке. Важно для SEO.

3️⃣ Правильно выбрать топики. Делается там же, где и описание. По таким топикам я нашел много OSS проектов – еще один бесплатный канал SEO для вас

4️⃣ LICENSE - ОБЯЗАТЕЛЬНО. Без лицензии ваш проект не более чем игрушка. Никто не будет рассматривать его использование на продакшене. Можете посмотреть шаблоны тут и сравнить их тут. Если у вас нет никаких особых планов - просто воткните MIT. Ну или пивную лицензию (хотя бы полезно)

5️⃣ лейблы (badges / shields) в README - это тоже очень важно. Эти лейблы быстро распознаются юзером и помогают понять, в каком состоянии проект. Почти все можно оформить тут. Там обязательно должно быть:
– последняя версия библиотеки, которую можно скачать (pypi / npm / etc)
– code test coverage - это оч важная цифра для нового проекта. Наличие coverage 95% показывает пользователям, что хотя у вас и не много звезд / скачиваний, вы все равно думаете о качестве. Это дает им какую-то уверенность, что ваш проект можно взять и не обжечься
– количество установок (в день / неделю / месяц) - можно добавить чуть позже, когда будет что показать. Но это тоже отличный способ показать "смотри, нас уже кто-то юзает. Ты тоже можешь".
– поддерживаемые версии языка (python в моем случае). Чтобы юзеры понимали сразу, подходит ли им проект. Или мб он уже устарел на 5 версий от хедлайн и проект скорее мертв, чем жив
– лицензия проекта
– другие пайплайны по вкусу - Sonar, Code Quality, Dependency Review и тд

6️⃣ ДОКУМЕНТАЦИЯ - без этого даже нет смысла запускаться. Сайтик на пару страниц делается на mkdocs с хостингом на GitHub Pages за вечер. Но он нужен. Причем сразу. Посадочной страницей имеет смысл продублировать README репозитория

7️⃣ examples/ примеры кода - пока проект маленький оч удобно держать такую мини-доку прям в коде. Люди смогут дергать куски кода для понимания работы каждой фичи. Они точно это оценят

8️⃣ Настроить CI - форматеры, линтеры, автоматический запуск тестов... OpenSource - это про качество и про контрибуторов. Без CI не будет ни того, ни другого
– также очень важно добавить запуск тестов по крону (раз в сутки / неделю), чтобы отлавливать несовместимости с релизом новых версий ваших зависимостей

9️⃣ CONTRIBUTING - небольшой (или огромный) гайд о том, как запустить ваш проект локально, вносить изменения, запускать линтеры, тесты и тд. Без этого людям тяжело приносить PR'ы. А вам нужна их помощь

Дополнительные советы закину в комменты. Обязательно отпишите свои рекомендации по оформлению репозитория и делитесь полезными ссылками для этого! Я сам постоянно ищу что-то прикольное, мб возьму и ваши советы на заметку🌚

#opensource