Подсказка: документация, документация, документация.

Настройка вашего проекта на успех

Не так давно я написал пост о проекте с открытым исходным кодом, который я опубликовал в The New York Times. Хотя у меня был некоторый опыт участия в программном обеспечении с открытым исходным кодом (OSS) в прошлом, это был мой первый запуск проекта с открытым исходным кодом, в котором я был единственным участником и хотел, чтобы другие использовали то, что я написал, в своих собственных проектах. Как человек, получивший выгоду от множества невероятных проектов OSS, я имел некоторое представление о том, как выглядит хорошее репозиторий с открытым исходным кодом на GitHub: в нем должен быть файл README.md, инструкции по установке и достаточно документации для начала работы. Но помимо этого, я был полностью растерян: что могло бы сделать мое репо из хорошего в отличное?

Далее следует краткое руководство, основанное на моем собственном опыте, по передовым методам создания проекта с открытым исходным кодом. Большая часть того, что я узнал, была обнаружена в ходе онлайн-исследований, бесед с коллегами и друзьями и проверки десятков проектов, доступных на GitHub.

Документация - ключ к успеху

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

Есть несколько мест, где вы можете разместить важную информацию, но самое центральное и доступное находится в корневом файле проекта README.md.

Начните с README

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

Почему существует ваш проект. Какой цели он служит и кому он служит? Это своего рода заявление о миссии, которое должно быть заметно для всех, кто впервые посещает репо.

Инструкции по быстрому запуску. Обычно включает инструкции о том, как максимально быстро и легко загрузить и использовать код.

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

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

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

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

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

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

Помогая другим вносить свой вклад

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

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

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

Инструкции по тестированию. Если в вашей кодовой базе есть тесты, которые необходимо пройти для рассмотрения любого PR, включите инструкции о том, как запускать тесты для вашего проекта и как писать дополнительные тесты для предложенных участником изменений.

Шаблон проблемы. Четко определите информацию, которую вы хотите включить в новые проблемы. Такие подробности, как вид регистрируемой проблемы (ошибка, запрос функции, изменение документации), версия ОС, браузер, особенности языка / среды и шаги, которые необходимо воспроизвести, могут сэкономить вам и сотрудникам часы отладки. Чтобы помочь журналистам написать полезную проблему, рассмотрите возможность включения шаблона проблемы, который будет предварительно заполнять новую проблему той информацией, которую вы ожидаете включить.

Раздел о лицензии вашего репозитория. Наличие лицензии защищает вас, ваших участников и всех, кто использует вашу работу. Знание того, какая лицензия подойдет вам и вашей аудитории, вероятно, является самой сложной частью проверки этого требования, но selectalicense.com и tl; dr legal облегчают любому принятие осознанного решения.

Идти на лишнюю милю

Тщательный README, рекомендации и полезные шаблоны - это только начало подготовки вашего проекта OSS к запуску. Хотя их можно считать «голыми костями» любого достойного проекта, существует множество дополнительных шагов, которые вы можете предпринять, чтобы создать проект, который приятно использовать и в который будет вносить свой вклад.

Убедитесь, что ваша кодовая база в безопасности. Ваш код могут использовать или увидеть десятки, сотни или даже тысячи людей. Примите меры предосторожности, чтобы защитить свои учетные записи, следуя передовым методам, таким как сохранение паролей и секретов из истории git, регулярное сканирование безопасности вашей кодовой базы и поддержание ваших зависимостей в актуальном состоянии с помощью последних пакетов безопасности. К счастью, GitHub упрощает эту задачу, предоставляя автоматические предупреждения безопасности для общедоступных репозиториев, чтобы вы могли быть в курсе последних уязвимостей в своих проектах.

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

Используйте анализатор кода. Линтеры могут помочь отловить мелкие ошибки, такие как использование табуляции вместо пробела, и большие ошибки, например, когда вы забудете точку с запятой, могут быть абсолютно пагубными (* кашель * PHP * кашель *). Они также дают вам возможность применять определенные стили кодирования без необходимости лично применять стили кодирования посимвольно.

Включите перехватчики git. Git Hooks - это команды или скрипты, которые автоматически запускаются до того, как в Git произойдут определенные действия. Они могут подключаться к нескольким различным командам git - commit, push, merge и т. Д. - и используются для автоматического запуска процессов, которые вы сочтете необходимыми до или после этих команд. Например, многие инженеры используют перехватчики git, которые запускают тесты перед фиксацией или отправкой; Если тесты не пройдут, фиксация или push завершатся ошибкой. Это добавляет еще один уровень защиты к проекту, автоматически отклоняя любые изменения кода, которые нарушают тесты или не соответствуют стандартам линтинга, прежде чем они когда-либо попадут в PR или главную ветвь.

Добавьте инструменты непрерывной интеграции / разработки. CI / CD отлично подходят для автоматизации рутинных задач, связанных с проверкой, поддержкой и отправкой кода. Это может быть что угодно, от назначения кого-то для выполнения проверки кода PR до развертывания ветки в промежуточной среде. Для любого типа проекта доступно море ресурсов и инструментов, поэтому я не буду вдаваться в подробности здесь. Но Apps Marketplace на GitHub - это набор инструментов, которые можно интегрировать в любой проект.

Включите файлы конфигурации редактора / среды IDE. Помогите участникам настроить свои редакторы кода или среду IDE для работы в рамках ограничений вашего проекта, чтобы сократить время, затрачиваемое участниками на изменение настроек. Популярные (и бесплатные) текстовые редакторы, такие как VSCode и Atom, позволяют вам контролировать такие настройки, как использование табуляции или пробелов в проекте, автоматический запуск линтеров при сохранении и многие другие.

Добраться до этого

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