Советы по работе с GitHub

Вот уже 6 лет как я занимаюсь в той или иной мере разработкой веб-приложений. За это время мы с командой работал над большими и малыми eCommerce проектами. Первые 4 года везде мы использовали Github в качестве репозитория версионирования, затем начали плавно мигрировать на Gitlab. Сейчас мы выбираем по-умолчанию GitLab, если нет никаких препятствий со стороны заказчика.

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

[sendpulse-form id=”278″]

Есть много признаков качественного ПО: надёжность, устойчивость, модульность, безопасность, производительность, масштабируемость, удобство в использовании, тестировании и сопровождении. И много других признаков, в зависимости от типа приложения. В этой статье я сосредоточусь на таких свойствах:

Хорошая документация: readme, сайты с документацией и журналы изменений.
Подробно расписанные соглашения и стандарты кодинга.
Правильное версионирование с помощью семантического версионирования.
Автоматизированные тесты: используем их не слишком много, сосредоточимся на функциональных нерегрессионных тестах.
Конечно же, счастье разработчика!

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

Если вы работает в open source-проекте, то наверняка хотите публиковать свой Github-проект. Git и Github полностью изменили способ разработки OSS, де-факто превратившись, соответственно, в стандартный язык версионирования и площадку для сотрудничества.

Официально предлагаемый Github’ом рабочий процесс называется github flow. Он прекрасно описан на сайте. Этого процесса, с небольшими вариациями, придерживается большинство open source-проектов.

Github Flow очень гибок в том смысле, что он не диктует вам, как нужно релизить и документировать изменения, какую стратегию слияния использовать, когда принимать pull request’ы, какие инструменты применять, каким стандартам коммитов следовать или что нужно рецензировать перед принятием pull request’а. Всё это отдано на ваше усмотрение, и правильно сделано, поскольку не существует универсальных решений, подходящих всем командам.

Дальше я приведу список рекомендаций на основе моего опыта.

Приоритезируйте задачи и отслеживайте прогресс с помощью Github Projects

В сентябре 2016 появилась фича Projects. Это инструмент, позволяющий создавать доски в стиле Kanban для упорядочивания, приоритезации и отслеживания работы на уровне репозитория и организации. Если у вас есть затруднения с использованием Github, настоятельно рекомендую освоить Projects для организации и обмена информацией о приоритетах проекта и текущих усилиях.

Подробнее

Классифицируйте задачи с помощью тегов

Github имеет превосходные возможности по фильтрации. Если вы работаете над open source-проектом, то наверняка заинтересованы в привлечении других участников, а также в том, чтобы им было удобно. Если помечать свои задачи тегами, разработчикам легче будет ориентироваться в списке, это сэкономит им время и облегчит работу над проектом.

Используйте Github-шаблоны для pull request’ов и задач

Не пожалейте времени на написание Guthub-шаблонов для pull request’ов и информирования о проблемах. Это заставит других разработчиков — или хотя бы поможет им — слать отчёты о багах и запрашивать создание фич неким стандартным способом, прикладывая всю необходимую вам информацию.
Подробнее

Основные советы по отчётам о багах:

Прежде чем отправлять информацию о проблеме:

Удостоверьтесь, что пользуетесь последней версией.
Поищите упоминание об этом баге, возможно, отчёт о нём уже был раньше.

Отчёты о багах должны содержать:

Краткое описание.
Как вы столкнулись с багом? Инструкция по воспроизведению.
Какого поведения вы ожидали от приложения?
Как приложение повело себя на самом деле?
Ссылки на все связанные с ситуацией тикеты или информационные источники.
По мере возможности, прикрепите визуальное подтверждение бага. Скриншоты, видео и/или анимационные гифы.

Общие рекомендации по pull request’ам:

Проверьте, что по вашей проблеме ещё нет других pull request’ов.
Проверьте в баг-трекере, не было ли проблем, связанных с вашим багом.
Нетривиальные изменения лучше предварительно обсудить.
Сообщите нам, над какой задачей работаете.
Разрабатывайте в конкретной тематической ветке, а не в мастере.
Напишите описание полезного pull request’а.
Соблюдайте рекомендации по коммитам в проекте.
Напишите хорошее описание своего pull request’а.
Укажите в описании ссылку на Github-задачу.

Пользуйтесь командной строкой

Консоль — ваш друг. По моему опыту, освоение работы с Github через командную строку — лучшая трата времени, когда работаешь с open source-технологиями. Да, существует много хороших графических интерфейсов, но все они менее гибки в использовании. Кроме того, есть инструменты только под командную строку, которые сильно упрощают жизнь и повышают эффективность разработки:

hub — обёртка для Git, облегчающая работу с GitHub. Не важно, новичок вы или опытный open source-разработчик, hub облегчит извлечение репозиториев, навигацию по страницам проекта, работу с форками и даже отправку pull request’ов. И всё это из командной строки. hub.github.com
tj/git-extras — набор Git-утилит, таких как сводка по репозиторию, repl, журнал изменений, статистика коммитов по авторам, и многое другое. github.com/tj/git-extras

Соблюдайте строгие стандарты коммит-сообщений и категоризируйте коммиты

Всегда определяйте и соблюдайте ясные стандарты написания коммит-сообщений. Вот некоторые рекомендации:

Коммитьте каждый фикс как отдельное изменение.
Пишите полезные коммит-сообщения.
Пишите короткое коммит-сообщение в первой строке (50–100 символов). Если посмотрите результат выполнения gitk или git log –oneline, то поймёте, почему.
Ссылайтесь на Git-задачу в теле коммит-сообщения.

Кроме того, для улучшения генерирования журнала изменений настоятельно рекомендую распределять сообщения по категориям (scope). Тогда ваши журналы изменений будут информативнее. Прекрасный пример: соглашения о коммитах и генерирование журналов изменений в AngularJS.

Определяйте стандарты оформления кода и конфигурируйте прекоммит-хуки

Для написания удобного в сопровождении кода очень важно определять стандарты оформления и соблюдать их в прекоммит-хуках (pre-commits hooks). Стандарты помогут поддерживать единообразие кода вне зависимости от того, кто его пишет, а также помогут принимать и сопровождать код, написанный кем-то другим.

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

typicode/husky — прекрасный инструмент для конфигурирования прекоммит-хуков.

Используйте автоматизированные тесты и проверки pull request’ов

Очень желательно автоматизировать функциональные тесты и проверки безопасности и стиля оформления кода в каждом pull request’е. Вряд ли вы захотите всё это делать вручную. Можно быстро сконфигурировать сервер непрерывной интеграции, вроде TravisCI, чтобы автоматически прогонять тематическую ветку через тесты после отправки каждого pull request’а. Также можно сконфигурировать Github, чтобы он не позволял разработчику присоединять pull request’ы, если те не прошли тесты. При сбое тестов Github покажет автору сообщение, чтобы он исправил свои pull request’ы.

Подробнее.

Защищайте свою мастер-ветку и требуйте проводить ревизию кода

Github позволяет защищать мастер-ветку от прямых коммитов, принудительных push’ей и перебазирования. Это очень важно, когда работаешь с кем-то над проектом. Кроме того, обязательно требуйте проводить ревизию кода, прежде чем объединять его с мастер-веткой. Это задаётся во вкладке настроек каждого репозитория.

Защитив мастер-ветку и включив принудительную ревизию, вы будете знать, что нежелательный код вряд ли попадёт в мастер и что никто в команде не подставит остальных, изменив Git-историю мастер-ветки или запушив непроверенный код.

Сквошьте свои pull request’ы

Много споров о том, что правильно: объединять, сквошить (squash) или перебазировать. Я считаю, что лучше всего сквошить, потому что:
Не все разработчики знают, как правильно перебазировать pull request поверх мастер-ветки. Многие просто мёржат мастер поверх своих изменений. Сквошинг позволяет избавиться от merge-сообщений, которые бесполезны для будущего формирования журнала изменений и просто зашумляют Git-лог.

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

Чтобы успешно выстроить рабочий процесс на основе сквошинга, необходимо все pull request’ы категоризировать по конкретным фичам, исправлениям багов или рутинным задачам.

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

Учитывая шаблон MAJOR.MINOR.PATCH, увеличивайте:
Старшую (MAJOR) версию, если вносите несовместимые с предыдущими версиями изменения в API.

Младшую (MINOR) версию, если добавляете обратно совместимую функциональность.
Патч-версию (PATCH), если вносите обратно совместимые исправления ошибок.

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

Помимо изменения версии package.json, рекомендую для каждой версии генерировать git-тег.

Подробнее.

Спецификация Conventional Commits подразумевает при написании коммит-сообщений соблюдение простого стандартизированного соглашения. Оно увязано с соглашением SemVer, которое просит разработчиков описывать в коммит-сообщениях все фичи, исправления и критические изменения. Соблюдая соглашение, мы создаём стандартный язык, упрощающий отладку в различных проектах.

Подробнее.

Автоматизировать этот процесс поможет TravisCI.

Также обратите внимание на эти пакеты: dominique-mueller/automatic-release, semantic-release/semantic-release.

Автоматизируйте развёртывание с помощью тег-хуков

Не обязательно использовать ветки релизов, как это предлагается в рамках Git Flow. Можно брать артефакты развёртывания из Git-тегов. Здесь описано, как с помощью TravisCI развернуть Git-теги в heroku. Это очень просто, нужно лишь для атрибута тегов задать значение true. Такое поведение можно реализовать с помощью любого другого CI-сервера.

Для среды разработки можно настроить хук, который развёртывает последний мастер-коммит. А для сред комплектов (feature environments) можно использовать и не такие долгоживующие ветки; при желании, для каждого PR-запроса вы можете предоставлять временную тестовую среду, но такой подход сложнее, да и не является обязательным.

Настройте потоковый Github-канал для чата

Очень удобный способ отслеживания активности в ваших Github-репозиториях из места, идеально подходящего для взаимодействия с командой: простой поток уведомлений в одном или нескольких чатах. К слову, в чатах вы можете делать и многое другое, в 2013-м на Github появился термин ChatOps, подробнее о нём рассказывается здесь.

Автоматизируйте обновление зависимостей

Нам приходится регулярно тратить много времени на актуализацию зависимостей. Это идеальная задача для автоматизации. Существует много инструментов, помогающих поддерживать зависимости «свежими», автоматически создавая в проекте pull request’ы с последними версиями. Эти запросы будут прогнаны через автоматизированные нерегрессионные тесты, и если пройдут успешно, то можно надеяться, что код после объединения будет работать нормально. Будьте осторожны с изменениями уровня старших версий, дважды всё проверяйте.

Пара полезных инструментов: greenkeeper.io и david-dm.org.

С помощью расширений улучшайте работу с интерфейсом Github’а

Open source-разработчики создали много полезных расширений, улучшающих работу с интерфейсом Github’а. Например:

GitHub Avatars [chrome] — отображает аватары в новостной ленте.
GitHub Awesome Autocomplete [chrome] [firefox] — добавляет функцию мгновенного поиска в поисковый блок GitHub.
GitHub Categoric [chrome] — категоризирует ваши смешанные GitHub-уведомления.
GitHub Hovercard [chrome] [firefox] — удобный GitHub-плагин hovercard для пользователей/репозитория/задач.
GitHub Isometric Contributions [chrome] [safari] — отображает вклад в проект разных людей в виде изометрического pixel art-графика.
GitHub Linker [chrome] — линкует зависимости в пакете или bower-файле с их GitHub-страницами.
GitHub Octotree [chrome] [safari] [firefox] [opera] — отображает GitHub-код в виде дерева.
GitHub Selfies [chrome] — добавляет селфи в pull request’ы и комментарии.
GitHub Stars Tagger [chrome] — прямо в GitHub добавляет теги в ваши отмеченные звёздами (starred) репозитории.
Github NPM Hub [chrome] — позволяет исследовать npm-зависимости в GitHub-репозиториях.
Github vscode-icons [chrome] — показывает vscode-иконки в браузере репозитория.

Другие расширения: GitHub Browser Extensions.

На Kikobeats/awesome-Github есть ещё инструменты для улучшения вашего рабочего процесса.

Постоянная учёба и самосовершенствование

Github и методики разработки open source ПО постоянно развиваются, поэтому держите руку на пульсе новейших тенденций и инструментов, отслеживая Github-новости и соблюдая стандарты вашего сообщества. Прекрасный источник информации — Youtube-канал GitHub Training & Guides.