Статья рассчитана в первую очередь на новичков и тех кто только собирается опубликовать свой первый проект на GitHub. Те у кого уже есть опубликованные проекты также могут почерпнуть что-то полезное и написать свои лучшие практики в комментариях. В статье представлены пять простых советов как улучшить ваш GitHub проект.
1. Напишите хороший Readme
Это самый важный совет! Readme файл это лицо вашего проекта на GitHub, то как ваш проект увидит пользователь. Как часто вам приходилось видеть проекты без описания? Что вы думали о таком проекте? С большой вероятностью никто даже не будет смотреть код если readme файл пуст. Не стоит относиться к описанию проекта спустя рукава. Представьте что вы пишите описание проекта для себя самого, но только в самом начале карьеры программиста. Пишите так что бы любой мог разобраться.
Хороший readme по моему мнению состоит из следующих пунктов:
- Описание проекта в одно предложение, из него должно быть понятно назначение проекта.
- Как установить проект, тут либо ссылка на NuGet либо инструкция как собрать проект из исходников.
- Примеры работы с вашим проектом. Подойдут unit-тесты с подробными комментариями.
- Частые вопросы и способы их решения. Расскажите о проблемах с которыми вы уже сталкивались при работе с проектом.
- Лицензия и благодарности.
Не стесняйтесь использовать emoji в описании проекта.
2. Создайте NuGet пакет
NuGet сильно облегчит работу пользователя с вашим проектом, ему достаточно будет написать:
PM> Install-Package %YOUR_PACKAGE_NAME%
вместо сборки из исходников. NuGet пакет можно создать с помощью утилиты NuGet Package Explorer. Для тонкой настройки рекомендую использовать консольную утилиту nuget (подробное описание вы можете найти здесь). Описание пакета можете честно скопировать из readme. Не забудьте указать ссылку на GitHub в projectUrl. Публикация пакета это только полдела, необходимо поддерживать его в актуальном состоянии. Об этом поговорим в следующем совете.
3. Добавьте автоматическую сборку проекта и прогон unit-тестов
Автоматическая сборка и прогон тестов упростит вам поддержку проекта. Существует много сервисов которые предоставляют такие возможности. Я использую appveyor так как он бесплатен для open source проектов. Достаточно указать ваш GitHub репозиторий и с вероятностью 90% все заработает из коробки. Указав appveyor путь к .nuspec файлу и ваш apiKey вы получите автоматическую публикацию вашего проекта в NuGet при каждой удачной сборке (дополнительную информацию по настройке можно найти тут).
4. Добавьте бейджи
Этот совет опционален, конечно можно обойтись без бейджей. Но как же удобно видеть всю важную информацию о проекте в первой строке.
Бейдж со статусом последнего сборки проекта вы можете взять из appveyor. Бейдж с последней версией NuGet проекта можно взять отсюда. На просторах интернета вы найдете большое количество бейджей на все случаи жизни: версия .Net framework, количество скачиваний NuGet проекта, и т.д.
5. Уделяйте время сообществу
Последний, но не менее важный совет — уделяйте время сообществу которое образуется вокруг вашего проекта. Публикуя любой проект в open source — вы автоматически берете на себя ответственность за его поддержку. Отвечайте на вопросы, дополняйте документацию и развивайте проект.
Спасибо за внимание! Буду рад увидеть ваши полезные советы в комментариях, давайте вместе развивать .Net open source сообщество.
Автор: sochix
