Лучшие практики Open Source разработки

Начав работу над своим проектом, стоит придерживаться определенных стандартов и практик open source, которые помогут облегчить разработку и привлечь новых контрибьюторов и пользователей

Лицензия проекта

Важным шагом в работе на open source проектом является выбор лицензии. У любого программного продукта есть лицензионные соглашения, в которых установлены правила и ограничения их использования. Для ПО с открытым кодом доступен целый ряд лицензий, с которыми можно ознакомиться на ресурсе choosealicense.com или в более подробном гайде Лицензия для вашего open-source проекта.

Пакетный менеджер

Если для вашей платформы есть пакетный менеджер, имеет смысл опубликовать свой проект, и сделать его доступным для легкого скачивания и установки. В случае языка Python речь идет о пакетном менеджере pip, который по умолчанию устанавливает пакеты из основного индекса — PyPI.

Инструкции о публикации вашего пакета в PyPI-индекс можно найти по ссылке: Как сделать pip-пакет

Тестирование

Фактические тесты — единственный формальный способ работоспособность кода потенциальному пользователю. Кроме того, тесты позволяют избежать случайных ошибок практически на всех этапах разработки. В сервисе GitHub есть функциональность GitHub Actions, позволяющая в автоматическом режиме запускать проверки вашего кода при определенных триггерных событиях, например, таких как Pull Request или Push. Более подробную информацию можно получить в материале Настройка GitHub Actions для автоматизированного тестирования средствами Python в конвейере CI/CD

Документация

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

README.md

Фактически ReadMe-файл – лицо вашего open source проекта, минимальная обязательная документация со всей необходимой для начала работы информацией.

В частности, в ReadMe имеет смысл осветить следующие пункты:

С типовым шаблоном readme.md можно ознакомиться по ссылке

CONTRIBUTING.md

В этом файле, как правило, содержится информация о том, каким образом потенциальные контрибьюторы могут участвовать в проекте и внести свой вклад в его развитие. В отличие от README.md, в нём размещается пошаговая инструкция процесса разработки: начиная от клонирования репозитория и внесения изменений в код, заканчивая созданием pull request и прохождением code review. Пример CONTRIBUTING.md файла с подробным описанием разделов можно найти по ссылке

Changelog

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

В целом есть два способа ведения этого файла: ручной и автоматический. В ручном способе разработчику необходимо явно фиксировать информацию о внесенных в проект изменениях. Автоматический же предполагает автоматическую генерацию этого файла на основе сообщений в коммитах. Более подробно о ведении и структуре changelog файла можно прочесть в материалах CHANGELOG.md: ручное и автоматическое ведение истории изменений проекта в Git и Что такое changelog проекта и как его создать: руководство по Git для начинающих

Подробная документация, примеры

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

GitHub процессы

Коммиты

В идеале коммиты должны быть небольшими и содержать в себе изменения, ограниченные отдельной идеей.

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

Более подробную информацию о том, как писать комментарии к коммитам можно найти в статье Как следует писать комментарии к коммитам

Метки для Issues

В развивающемся проекте со временем появляются запросы на новую функциональность, находятся ошибки, возникает необходимость в рефакторинге кода. Обычно подобные запросы фиксируются в виде отдельных issues для планирования и отслеживания работы, но их большое количество в какой-то момент усложняет навигацию по задачам проекта и запутывает потенциальных контрибьюторов. Хорошей практикой в таком случае будет добавление соответствующих меток к каждой из задач, например “good first issue”, “bug”, “enhancement” и т.д.

С подробным описанием возможной структуры меток можно ознакомиться в статье GitHub Issues: Tagging Best Practices - Save Time!, а общую информацию об использовании issues найти в официальной документации GitHub

Pull Request & Issues templates

Для большей структуризации и приведения issues и pull request’ов вашего проекта к единому формату можно использовать специальные шаблоны, унифицирующие issues и PR для всех контрибьюторов. Примеры таких шаблонов можно посмотреть по ссылке GitHub pull request template

Return to Homepage