- PVSM.RU - https://www.pvsm.ru -
Github это незаменимый инструмент, прочно вошедший в жизнь практически каждого разработчика.
Хотя многие из нас используют его постоянно, не все знают, что существует большое количество сторонних (и бесплатных) сервисов и инструментов, которые тесно интегрированы с github и расширяют его функциональность.
Естественно, будут рассмотрены не все инструменты. Полный список сервисов, интегрирующихся с github, можно посмотреть на странице github integrations directory [8].
Большинство рассмотренных сервисов предоставляет информационные значки (badges), которые можно добавить на страницу проекта. Чтобы не показывать одну и ту же картинку при каждом упоминании badge, покажем ее один раз в начале статьи:
Основное внимание мы уделим платформе node.js.
Также нам понадобится написать несколько скриптов. Для этого мы будем использовать npm script-ы, избегая таких инструментов как grunt или gulp, так что знание специфических сборщиков вам не понадобится.
Мы на личном опыте убедились, что эта мысль правильная.
Если вы собираете свой проект, к примеру, при помощи gulp, то для каждого используемого инструмента приходится искать (или писать самому) плагин. Например, для компиляции typescript [12] нужно использовать gulp-typescript [13], для запуска tslint [14] нужен gulp-tslint [15], для запуска typedoc [16], нужен gulp-typedoc [17]. Ну и так далее.
Инструменты периодически обновляются и иногда вы ну очень ждете вышедшее обновление. Бывает, что плагины обновляются с некоторой задержкой. И бывает, что и не обновляются вовсе.
Например, не так давно вышел долгожданный релиз typescript 2.x. Не заставили себя долго ждать обновления tslint и typedoc. А вот новые версии плагинов выходить не торопились. В итоге, проект было невозможно перевести на новую версию typescript из-за старой версии gulp-плагина для вообще вспомогательного инструмента.
Вдобавок, плагины это дополнительные зависимости в вашем package.json, и у них нередко бывают ещё зависимости, и так далее. Все это напрямую сказывается на времени установки, например, при запуске билда в travis.
В общем, наш опыт показал, что если переписать сборку на npm-скрипты, то жизнь становится проще.
А еще очень здорово не использовать инструменты, которые требуют глобальной установки. Но эту мысль мы не будем обсуждать в деталях и просто поделимся ссылкой на неплохую статью [18] для заинтересовавшихся.
Живые примеры использования описанных сервисов можно посмотреть в наших репозиториях библиотеки e2e4 [19] (простые варианты) или библиотеки angular-гридов right-angled [20] (варианты поинтереснее).
Начнем с очевидного — каждому проекту нужен continuous integration. Тут нам на помощь готов прийти travis ci [21].
Настройка билда в travis достаточно проста и состоит из следующих шагов:
Например, вот так:
language: node_js
node_js:
- "6"
script:
- npm run ci
Так мы сообщаем travis, что нам необходимо окружение с nodejs версии 6.
Процесс билда состоит из одной npm-команды, которая запускает скрипт с названием “ci”, из секции “scripts” файла package.json.
В нашем случае эта команда по очереди выполняет lint проекта с tslint [14], сборку с typescript [12], и прогоняет тесты при помощи karma [22]. Если вам интересны детали, то можно посмотреть их в package.json на github [23].
Также обратите внимание, что в командах билда мы не прописывали “npm install”. Travis сам понимает, что необходимо выполнить установку зависимостей через npm и выполняет ее.
Более того, если вы используете yarn, то travis поймет это, установит yarn [24] и выполнит установку зависимостей с помощью него.
В travis заложено множество подобных шаблонов, которые избавляют нас от лишних действий.
Теперь выполняем push файла “.travis.yml’, после чего будет выполнен первый билд. Процесс билда можно наблюдать в реальном времени на странице travis.
Следующий сервис, с которым мы познакомимся, это coveralls [26].
Общая идея состоит в том, что при прогоне тестов вы генерируете отчет о покрытии в формате lcov и отправляете его в сервис coveralls для анализа. Сервис ее обрабатывает и и предоставляет следующие возможности:
Чтобы подключить coveralls к вашему проекту, необходимо выполнить следующие шаги:
Мы не будем рассматривать способы генерации отчетов о покрытии в деталях, поскольку все зависит от того, на чем вы пишете тесты, какие инструменты используете, и как тесты запускаете. Плюс, к примеру, для typescript нет инструментов генерации coverage reports, поскольку запускается на исполнение не typescript, а javascript. И, если вам хочется смотреть покрытие именно typescript кода, то понадобятся инструменты для ремаппинга отчетов о покрытии js-кода обратно на код typescript. Все это излишняя специфика, которой мы стараемся избегать в данной статье. Начать изучение возможных вариантов можно со странички npm-пакета coveralls на github.
"scripts": {
"coveralls": "cat ./coverage/lcov.info | ./node_modules/.bin/coveralls",
...
}
language: node_js
node_js:
- "6"
script:
- npm run ci
after_success:
- npm run coveralls
Помимо github, coveralls интегрируется с bitbucket и обещается скорая поддержка gitlab. Также поддерживается интеграция со множеством сервисов continuous integration и множеством платформ разработки.
Сервис мониторинга зависимостей david [29] будет самым простым из рассматриваемых в статье.
Идея сервиса проста — мы добавляем на страницу проекта badge, который является индикатором состояния зависимостей проекта. Он же является ссылкой на страничку анализа зависимостей проекта.
Чтобы подключить к нашему проекту david, набираем в браузере адрес по следующему шаблону:
https://david-dm.org/<имя аккаунта>/<название репозитория>
В зависимости от того, какие типы зависимостей есть в вашем проекте, на открывшейся странице вы увидите вкладки “dependencies”, “devdependencies”, “peer dependencies” и “optional dependencies”.
На каждой из вкладок приведен список зависимостей определенного типа и badge, кликнув на который можно скопировать ссылку в формате markdown или HTML и разместить ее у себя в файле readme или на страничке проекта в github pages.
Также существует утилита david cli [30], призванная помочь в обновлении зависимостей на вашей машине. Правда мы так и не смогли понять, в чем ее преимущества по сравнению со встроенными командами npm outdated [31] и npm update [32].
Сервис greenkeeper [33] также призван помочь нам в нелегком деле обновления зависимостей, но делает это на куда более высоком уровне. Его задача — по возможности полностью избавить нас от работы с зависимостями.
Чтобы подключить greenkeeper к нашему проекту, необходимо перейти на страницу greenkeeper в разделе public integrations на github [34] и установить приложение в нужный нам репозиторий.
Буквально через минуту greenkeeper создаст pull request, в котором обновит все зависимости вашего проекта и добавит в readme badge, отображающий статус greenkeeper.
Только если вы сделаете merge данного pull request-а, greenkeeper начнет мониторить ваш проект.
Далее, при появлении новых версий зависимостей greenkeeper будет создавать pull request-ы, в которых будет приводить детальное описание, что было обновлено и по возможности приведет список изменений в новой версии. Вам остается только сделать merge.
Естественно, подключение greenkeeper имеет смысл только если у вас настроен автоматический билд и имеются тесты, при помощи которых можно хотя бы номинально проверить, что ваш проект находится в рабочем состоянии после обновления. Greenkeeper распознает, есть ли в вашем репозитории билд и тесты, и пишет предупреждение в тексте pull request-а, если не обнаруживает того или другого.
"greenkeeper": {
"ignore": [“список”, “зависимостей”, “которые”, “не нужно”, “обновлять”]
}
Commitizen [38] это целый набор инструментов, помогающих в деле написания содержательных сообщений к коммитам.
Помимо большей информативности для людей, заинтересованных в вашем репозитории, использование commitizen имеет еще один плюс. Из генерируемых commitizen сообщений можно легко собирать changelog-и и release notes. И есть даже утилиты, анализирующие историю коммитов и подсказывающие, какой должен быть следующий номер версии, чтобы соответствовать конвенции semver [39]. Но об этом в следующем разделе.
А начнем мы с самого простого. Установим cz-cli [40]. После установки мы можем использовать команду “git cz” вместо “git commit”. Данная команда запускает визард, который проводит нас через серию вопросов о том, что именно мы изменили в текущем коммите и генерирует сообщение коммита в формате [41], который одновременно легко читается человеком и парсится различными инструментами.
Итак:
npm install commitizen -g
commitizen init <название адаптера> --save-dev --save-exact
Вместо <название адаптера> необходимо указать один из возможных адаптеров [42]. В мире front end разработки наиболее популярным является cz-conventional-changelog, следующий нотации сообщений, разработанной командой angular [43]
Данная команда установит необходимые зависимости, сохранит их в секции devDependencies файла package.json и там же пропишет необходимые настройки.
После того, как мы подключили commitizen, мы получаем еще одну опцию — возможность настроить автоматическую генерацию changelog-а и release notes.
Поможет нам в этом conventional-changelog [46].
conventional-changelog это целое семейство инструментов, при помощи которых можно построить выпуск релиза как при помощи высокоуровневых инструментов по готовым шаблонам, так и собрать из отдельных инструментов то, что нужно конкретно вам.
Сами разработчики рекомендуют использовать standard-version [47], который является относительно высокоуровневым инструментом.
Еще более высокоуровневым является semantic-release [48]. Данный инструмент даже сам делает push изменений и публикует версию в npm.
Из нашего опыта — попробовав оба варианта, мы остановились на использовании более низкоуровневых инструментов.
Причина такого выбора в том, что standard-version, например, не делает push изменений и не генерирует описание релиза на github. Добавление к процессу релиза таких вещей плюс настройка через опции standard-version запуска билда, или генерации документации вкупе требуют настройки, которая по сложности сопоставима с ручной настройкой процесса публикации на основе команды npm version [49].
Semantic-release, с другой стороны, пытается автоматизировать процесс целиком и для его использования необходимо очень дисциплинированно подходить к разработке. Сложность его настройки также сопоставима с ручной настройкой процесса. И последнее. Semantic-release делает npm publish, что ограничивает его использование только для библиотек, распространяемых через npm, а публиковать версии можно не только для библиотек.
Итак, мы построим процесс релиза на основе npm version. Также при запуске скрипта version npm самостоятельно запускает скрипты preversion и postversion, если таковые имеются. Мы будем использовать оба. Процесс выпуска релиза будет состоять из следующих шагов:
На примере репозитория e2e4 [23], данные шаги идентичны выполняемым в хуке precommit, поэтому мы используем тот же скрипт:
{
"preversion": "npm run precommit",
"precommit": "npm run rimraf -- esm coverage && npm run clean:src && npm run clean:tests && npm run lint && npm run build && npm run test"
}
Итого, получается следующий набор скриптов:
{
"version": "npm run docs && git add -A docs && npm run changelog && git add CHANGELOG.md",
"changelog": "npm run conventional-changelog -- -p angular -i CHANGELOG.md -s",
"docs": "npm run rimraf -- docs && typedoc --options typedoc.json src/"
}
Скрипт для version:
{
"postversion": "git push && git push --tags && conventional-github-releaser -p angular",
}
Наш процесс выпуска релиза готов.
Запускаем скрипт командой:
npm version <номер версии или major/minor/patch>
Сгенерированные release notes выглядят примерно так:
Содержимое в changelog.md почти такое же, поэтому мы не будем его приводить.
О сервисе zube.io [55] мы не будем рассказывать много. Каждый из нас работал с таск-трекерами и zube мало чем отличается от множества из них.
Назовем лишь два его достоинства, из-за которых мы решили упомянуть его в данной статье:
На этом мы заканчиваем наш обзор. Если вам известны другие интересные сервисы или инструменты для работы с github — пожалуйста, поделитесь своим знанием в комментариях.
Спасибо за уделенное внимание!
Изображение обложки для статьи — the Benevocats [56] by cameronmcefee.
Автор: EastBanc Technologies
Источник [57]
Сайт-источник PVSM.RU: https://www.pvsm.ru
Путь до страницы источника: https://www.pvsm.ru/git/249211
Ссылки в тексте:
[1] Настраиваем continuous integration c travis ci: #travis
[2] Настраиваем отчеты о test coverage с coveralls: #coveralls
[3] Мониторим статус зависимостей с david: #david
[4] Настраиваем автоматическое обновление зависимостей с greenkeeper: #greenkeeper
[5] Улучшаем сообщения коммитов с commitizen: #commitizen
[6] Генерируем changelog и release notes с conventional-changelog: #cz
[7] Управляем задачами с zube: #zube
[8] github integrations directory: https://github.com/integrations
[9] Cory House: https://medium.freecodecamp.com/why-i-left-gulp-and-grunt-for-npm-scripts-3d6853dd22b8
[10] grunt: https://gruntjs.com/
[11] gulp: http://gulpjs.com/
[12] typescript: https://www.typescriptlang.org/
[13] gulp-typescript: https://www.npmjs.com/package/gulp-typescript
[14] tslint: https://palantir.github.io/tslint/
[15] gulp-tslint: https://www.npmjs.com/package/gulp-tslint
[16] typedoc: https://github.com/TypeStrong/typedoc
[17] gulp-typedoc: https://www.npmjs.com/package/gulp-typedoc
[18] неплохую статью: https://www.sitepoint.com/solve-global-npm-module-dependency-problem/
[19] e2e4: https://github.com/eastbanctechru/e2e4
[20] right-angled: https://github.com/eastbanctechru/right-angled
[21] travis ci: https://travis-ci.org/
[22] karma: https://karma-runner.github.io/1.0/index.html
[23] package.json на github: https://github.com/eastbanctechru/e2e4/blob/master/package.json
[24] yarn: https://yarnpkg.com/
[25] документацию travis: https://docs.travis-ci.com/
[26] coveralls: https://coveralls.io/
[27] вот здесь: https://coveralls.io/github/eastbanctechru/right-angled
[28] coveralls : https://www.npmjs.com/package/coveralls
[29] david: https://david-dm.org
[30] david cli: https://www.npmjs.com/package/david
[31] npm outdated: https://docs.npmjs.com/cli/outdated
[32] npm update: https://docs.npmjs.com/cli/update
[33] greenkeeper: https://greenkeeper.io/
[34] public integrations на github: https://github.com/integration/greenkeeper
[35] version range: https://docs.npmjs.com/getting-started/semantic-versioning
[36] issue на github: https://github.com/greenkeeperio/greenkeeper/issues/314
[37] angular: https://www.npmjs.com/~angular
[38] Commitizen: https://github.com/commitizen
[39] semver: http://semver.org/
[40] cz-cli: http://commitizen.github.io/cz-cli/
[41] в формате: https://github.com/bcoe/conventional-changelog-standard/blob/master/convention.md
[42] один из возможных адаптеров: https://www.npmjs.com/package/commitizen#adapters
[43] нотации сообщений, разработанной командой angular: https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#-git-commit-guidelines
[44] vscode: https://github.com/KnisterPeter/vscode-commitizen
[45] добавить badge: https://github.com/commitizen/cz-cli#congratulations-your-repo-is-commitizen-friendly-time-to-flaunt-it
[46] conventional-changelog: https://github.com/conventional-changelog/conventional-changelog
[47] standard-version: https://github.com/conventional-changelog/standard-version
[48] semantic-release: https://github.com/semantic-release/semantic-release
[49] npm version: https://docs.npmjs.com/cli/version
[50] rimraf: https://www.npmjs.com/package/rimraf
[51] typedoc: http://typedoc.org/
[52] указать в настройках github: https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/
[53] conventional-changelog-cli: https://www.npmjs.com/package/conventional-changelog-cli
[54] братская библиотека для работы с gitlab: https://www.npmjs.com/package/conventional-gitlab-releaser
[55] zube.io: https://zube.io/
[56] the Benevocats: https://octodex.github.com/benevocats
[57] Источник: https://habrahabr.ru/post/323760/?utm_source=habrahabr&utm_medium=rss&utm_campaign=best
Нажмите здесь для печати.