Пять советов тому кто публикует свой .Net проект на GitHub

    GitHub Octocat Professor

    Статья рассчитана в первую очередь на новичков и тех кто только собирается опубликовать свой первый проект на 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. Добавьте бейджи


    Этот совет опционален, конечно можно обойтись без бейджей. Но как же удобно видеть всю важную информацию о проекте в первой строке.


    github badges

    Бейдж со статусом последнего сборки проекта вы можете взять из appveyor. Бейдж с последней версией NuGet проекта можно взять отсюда. На просторах интернета вы найдете большое количество бейджей на все случаи жизни: версия .Net framework, количество скачиваний NuGet проекта, и т.д.


    5. Уделяйте время сообществу


    Последний, но не менее важный совет — уделяйте время сообществу которое образуется вокруг вашего проекта. Публикуя любой проект в open source — вы автоматически берете на себя ответственность за его поддержку. Отвечайте на вопросы, дополняйте документацию и развивайте проект.


    Спасибо за внимание! Буду рад увидеть ваши полезные советы в комментариях, давайте вместе развивать .Net open source сообщество.

    Поделиться публикацией

    Комментарии 13

      0
      Я использую appveyor так как он бесплатен для open source проектов.

      Слабое утверждение. Travis CI тоже бесплатен, но собирается в линуксе, соответственно там Mono. А вот appveyor под Windows заточен.


      В принципе советы актуальны для любых проектов, не только .NET. За исключением может быть второго, да и то пакеты есть не только под .NET (npm).

        0
        По первому пункту согласен с вами. Travis CI как-то прошел мимо меня. Статью написал применительно к .net, т.к. количество и качество open source проектов на этой платформе сильно уступает тому же js. Хочу что бы в будущем эта ситуация поменялась.
          +2
          В этом и прелесть appveyor, что он собирает под Windows т.к. как это позволяет строить сборки PCL и конкретно сборки для Universal Windows Apps используя образ Visual Studio. К тому же, процесс сборки можно настроить до мельчайших деталей.

          Хотя лично я еще не разобрался, как настроить автоматическую публикацию NuGet пакетов в appveyor. В документации очень неясно описан этот процесс.

          Ну, а так использую Travis для JS проектов, а AppVeyor для .Net проектов.
            0

            Вот appveyor.yml с настроенной публикацией в NuGet. Если будут еще вопросы приглашаю в ЛС для обсуждения.

            0
            Почти для каждой среды есть свой пакетный менеджер. Так что втором пункте нужно только название менять.
            +9
            Мне кажется эти советы актуальны для любых проектов. Только вместо NuGet можно сказать чтобы люди делали инсталлятор.
              +2
              Только вместо NuGet можно сказать чтобы люди делали инсталлятор.
              … или выкладывали пакет на pypi/rubygems/npm/etc.
              0
              Для меня еще важен такой аспект, как документация самого кода т.е. методов, свойств и т.д.
              Иногда подключаешь стороннею библиотеку, вызываешь метод, который принимает три параметра типа object, и начинается «шоу интуиция». Или когда метод имеет несколько перегрузок. Это не менее важно, чем общая документация по проекту.
                0
                Примеры работы с вашим проектом. Подойдут unit-тесты с подробными комментариями.

                Я предлагаю описывать это в примерах работы с проектом
                +2
                > Публикуя любой проект в open source — вы автоматически берете на себя ответственность за его поддержку. 
                А если я его публикую как раз для того, что бы кто-то другой занялся его поддержкой? Что бы результат труда не пропал даром, когда бросаешь проект
                  0
                  Тогда надо прямо указать — нужен человек, который этим займется.
                    0
                    Спасибо за статью! У меня такой вопрос: а есть ли рекомендуемая или общепризнанная структура проектов на .NET? Структура каталогов, расположение тестов и т.д.?
                      0

                      Я использую расположение папок, которое предлагает Visual Studio: каждый проект и его proj файл в собственной папке, а sln файл лежит в корне.

                    Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.

                    Самое читаемое