Як прокачати свій open-source проєкт, використовуючи бейджики якості коду

Думаю, кожен, хто шукає щось на GitHub, час від часу стикається з репозиторіями, в яких у файлі README після назви проекту йде купа різних бейджиків. Вони виконують роль приладної панелі для репозиторію і показують, наскільки далеко з таким кодом можна зайти. Коли намагаєшся розібратися в цьому різноманітті бейджиків — настає хаос. Які сервіси мені потрібні? Що вони роблять? Як їх підключити? Де взяти робочий конфіг? Де взяти код для бейджика? Кілька разів наступивши на одні й ті ж граблі, я вирішив витратити трохи часу, щоб у цьому розібратися.

Дослідження

Досліджуючи цю тему, я прийшов до висновку, що бейджики найчастіше зустрічаються в репозиторіях перфекціоністів і альтруїстів. Якщо автор випустив у open source своє творіння і розвиває його, оперативно відповідає на запитання, фіксить баги, активно приймає пулл-реквести, стежить за якістю коду, то майже завжди такий репозиторій підключений до більшості сервісів оцінки коду. Чесно кажучи, приємно мати справу з такими людьми, вони заряджають тебе своєю енергією, і ти намагаєшся бути не гірше, ніж вони.

Сторонні сервіси, які зазвичай підключають до своїх репозиторіїв, можна грубо поділити на кілька категорій.

Безперервна інтеграція (CI)

Їх завдання — щоразу після комміту або пулл-реквеста (залежить від того, як налаштуєте) зібрати проект з усіх його вендорів. Після чого виконати тести (модульні, функціональні). Можна додати ще запуск різних утиліт, скриптів. Успішною вважається збірка, якщо в результаті виконання всіх команд кожна завершилася з exit 0. Код, відмінний від нуля, вказує на помилку. Результат може бути або «зеленим» — все ок. Або «червоним» — збірка не вдалася.

Покриття коду

Сервіси, які призначені для зручного перегляду звітів по покриттю коду тестами. За допомогою фреймворка для тестування (наприклад, PHPUnit) ви запускаєте всі тести з додатковою опцією по складанню звіту про покриття коду тестами. Рядок коду вважається покритим, якщо вона виконалася хоча б раз під час прогонки тестів. Враховуються тільки рядки з діючим кодом. Переноси, порожні рядки, опис функцій і класів, коментарі — не враховуються. Звіт, який виходить в результаті, потрібно передати на такий сервіс (робиться автоматично). А далі через браузер переглянути статистику покриття всього коду, кожного файлу, з підсвічуванням покритих і непокритих тестами рядків.

Аналізатори коду

Призначені для перевірки коду на best practice. Перевірка copy-paste, code style, аналіз архітектури коду, підказки по заміні одних конструкцій на інші, рекомендації до стандартних практик розробки тощо.

Кількість установок

Якщо для підключення необхідних пакетів ви використовуєте менеджер пакетів (наприклад, Composer в PHP) і свій код поширюєте також через менеджер пакетів, то, можливо, вам захочеться показувати статистику використання свого коду іншими людьми. Цю інформацію можна отримати безпосередньо з сайту менеджера пакетів або з іншого спеціального сервісу.

Ліцензія

У світі open source дуже важливо дотримуватися авторських прав (та й не лише у світі open source!). Тому знати, на яких умовах ви використовуєте чужий код, дуже важливо. Визначитися з ліцензіями можна безпосередньо перед вибором сторонньої бібліотеки. Але якщо проект у вас вже готовий, і ви раптом згадали про ліцензування, тоді можна скористатися спеціальними сайтами, які збирають інформацію про ліцензії різних пакетів. Підключивши свій репозиторій до такого сервісу, ви також можете захистити свій код і допомогти іншим розробникам, які бажають його використовувати. У процесі дослідження різних бібліотек, розміщених на GitHub, кілька разів я бачив issue, в якому автора просили додати до репозиторію файл з ліцензією, щоб була можливість використовувати його в комерційному продукті.

Усе інше

Сюди потрапляють усі невеликі цікаві сервіси, які не заслуговують окремої категорії. Вони можуть перераховувати розмір ваших вихідних файлів, підключати різні чати та канали зв'язку до ваших репозиторіїв, розміщувати ваші бібліотеки в рейтингах, базуючись на якихось показниках, і багато іншого. Про деякі цікаві сервіси я розповім.

Travis CI

Travis CI додався до списку інструментів open source-розробників і став де-факто стандартом. Він здобув свою популярність тому, що він безкоштовний, легко додається до GitHub, досить гнучкий для налаштування. Безкоштовна версія обслуговує публічні репозиторії, тому лог виконання кожного білда доступний усім бажаючим. Є й платні тарифні плани з більшими ресурсами.

Travis CI можна налаштувати таким чином, щоб він здійснював збірку проекту як після кожного комміту, так і тільки для пулл-реквестів. Він інтегрований у GitHub і показує статус збірки біля кожного пулл-реквесту. Якщо збірка зламана, то можна надіслати фікс з наступним коммітом, Travis перепровірить пулл-реквест, і він стане «зеленим».

У логах можна подивитися всю історію збірки, а також дізнатися, чому вона була неуспішною.

Щоб підключити свій репозиторій до Travis CI, потрібно:

• Створити в корені проекту файл .travis.yml і прописати в ньому необхідні налаштування;
• Залогінитися на Travis за допомогою акаунта з GitHub і підключити свій репозиторій до сервісу.

Travis дозволяє призначати команди на різні події: до початку збірки, до запуску скриптів, після виконання скриптів, тільки після успішного виконання скриптів тощо. Розпочати знайомство з документацією можна з цієї сторінки https://docs.travis-ci.com/user/getting-started. Travis підтримує безліч мов програмування, і якщо для збірки вашого проєкту потрібна якась стороння утиліта, то її можна доінсталювати консольною командою під час кожної збірки. Мінімальний приклад файлу .travis.yml для проєкту на PHP може виглядати ось так:

language: php

php:
  - 5.4
  - 5.5
  - 5.6

before_script:
  - composer install

script:
  - phpunit

notifications:
  email:
    - your@mail.com

Вказуємо, що використовується language: php. Перераховуємо версії, для яких потрібно зробити збірку — для кожної запуститься свій незалежний процес збірки. У секції before_script готуємо систему, в даному прикладі підтягуючи залежності проєкту через Composer. У секції script перераховуємо всі скрипти, які виконують перевірку нашого проєкту. У даному випадку виконуються модульні тести. Ну, і надсилаємо сповіщення на email по завершенню збірки.

Не буду заглиблюватися в деталі опцій .travis.yml, оскільки вони для кожної мови різні. Найкраще подивитися вже готові рішення, пошук на GitHub видає близько десяти мільйонів таких файлів.

Бейджик Travis буває двох кольорів, залежно від результату збірки.

Отримати код бейджика можна на сторінці репозиторію на сайті Travis, просто клікнувши на самому значку.

Чесно кажучи, складно уявити собі open source проєкт, який розроблявся б без Travis CI. На перший погляд не побачиш помилок, які прийшли в новому пулл-реквесті. Але якщо перед цим Travis CI прогнав всі тести, ви вже будете знати, в якому стані проєкт після впровадження нової фічі. Висновок — використовувати Travis CI обов'язково!

Scrutinizer

Scrutinizer — сервіс призначений для оцінки якості коду. Поки Scrutinizer обмежений підтримкою PHP, Python і Ruby, планується підтримка Java і Scala. Основні фічі цього сервісу:

• Виставляє оцінку вашому коду на основі показників, зібраних від різних аналізаторів;
• Зберігає історію зміни якості коду, можна на графіку подивитися, як розвивався проект;
• Сигналізує про проблеми у вашому коді з поясненням, до чого це може призвести. База знань досить широка;
• Також перевіряє вендори, які використовуються у вашому проекті, на наявність відомих security issue;
• Налаштування автоматичних звітів. Може спрацьовувати як на push, так і на pull-request, також можна задати періодичні автоматичні збори;
• Сервіс також інтегрований у GitHub і відображається в пулл-реквестах поряд з Travis (звісно ж, після додаткової настройки).

Для кожної мови програмування існують інструменти для аналізу коду. Наприклад, для PHP найпопулярніші — це:

• PHP Code Similarity Analyzer
• PHP Code Sniffer
• PHP CS Fixer
• PHP Mess Detector
• PHP Analyzer
• Security Advisory Checker

PHP Analyzer — потужний інструмент, ось список перевірок, які виконує Scrutinizer https://scrutinizer-ci.com/docs/tools/php/php-analyzer/checks.

Досить деякий час попрацювати з цим сервісом, і ви вже перестанете робити типові помилки, які постійно знаходить Scrutinizer у вашому коді. Щоб почати користуватися цим сервісом, по-перше, потрібно на ньому зареєструватися за допомогою GitHub. У особистому кабінеті підключіть свій репозиторій з GitHub. Розмістіть у корені вашого репозиторію файл .scrutinizer.yml. За замовчуванням більшість утиліт вже підключено. Scrutinizer пропонує вам почати з такого конфігу, в нього вже включено джентльменський набір аналізаторів:

checks:
  php:
    code_rating: true
    duplication: true

filter:
  excluded_paths:
    - vendor/*

before_commands:
  - "composer install --prefer-source"

Для проектів на Symfony я підключаю додатково ще пару утиліт, які вимагають явного включення:

checks:
  php:
    code_rating: true
    duplication: true

filter:
  excluded_paths:
    - vendor/*
    - app/*
    - bin/*
    - web/*
    - spec/*

before_commands:
  - "composer install --prefer-source"
tools:
  php_code_sniffer:
    config:
      standard: "PSR2"
  php_cs_fixer: true
  sensiolabs_security_checker: true

Сервіс надає три типи бейджиків. Але, по суті, значимим є тільки перший, який показує оцінку коду. Code coverage за допомогою Scrutinizer я не раджу вам робити, краще використовувати інший спеціалізований сервіс (далі в статті). Код бейджика можна взяти на сторінці репозиторію в особистому кабінеті, потрібно клікнути по іконці (i). Оскільки Scrutinizer призначений в першу чергу для open source, ви зможете переглянути список зауважень до будь-якого публічного репозиторію, який налаштований на роботу з цим сервісом.

Щиро рекомендую використовувати Scrutinizer для open source розробки.

Packagist

Packagist — це список бібліотек/фреймворків PHP, які можна встановити через менеджер пакетів Composer. Цікава для нас інформація, яку надає цей сервіс — це кількість установок та остання стабільна версія пакета. Вся ця інформація доступна на самому сайті, але було б добре додати її у свій репозиторій, щоб на сторінці репозиторію в GitHub вже побачити цікаву статистику. Packagist не надає свої бейджики для цього. Бейджики можна отримати на сторонньому сервісі Badge Poser. Вибираємо пакет і отримуємо код усіх доступних бейджиків.

Які саме бейджики ви хочете додати для відображення — це ваша справа. Зазвичай виставляють бейджики: загальна кількість установок, остання стабільна версія та ліцензія. Ліцензія визначається з файлу composer.json або з файлу LICENSE. Моя порада — завжди додавати три перелічені бейджики, вони несуть найкориснішу інформацію.

VersionEye

Сервіс VersionEye надає можливість слідкувати за версіями бібліотек, розміщених на GitHub. Насправді можна підключити й приватні репозиторії з GitHub, і працювати через API. Зараз сервіс підтримує наступні мови програмування: Java, Ruby, Python, Node.JS, PHP, JavaScript, Objective-C, R, Clojure.

Варіантів використання сервісу два. Можна зареєструватися на цьому сайті, знайти репозиторії, які вас цікавлять, і підписатися на них. Після виходу нових версій вам будуть приходити сповіщення на email. Так ви будете слідкувати за оновленнями потрібних вам бібліотек. Мій досвід показує, що від цього сайту сповіщення приходять раніше, ніж від офіційних джерел. Наприклад, про вихід нової версії PHP я дізнаюся ще до того, як новина з’являється на php.net. Також на цей сервіс можна додати свій публічний репозиторій. Це дасть вам можливість слідкувати за тим, як оновлюються бібліотеки та фреймворки, від яких залежить ваш код.

Поясню на прикладі PHP. Щоб ваш репозиторій моніторився за допомогою VersionEye, у корені вашого проєкту має бути файл composer.json. Якщо це не бібліотека або бандл, а, наприклад, веб-додаток — у більшості випадків у репозиторію також потрапляє файл composer.lock, в якому заморожуються версії використовуваних бібліотек. VersionEye на основі цих двох файлів проаналізує ваші залежності, зіставить версії, які використовуєте ви, з актуальними версіями, і покаже вам всю статистику. А також буде сповіщати щоразу, коли у вашому проєкті оновлюються зовнішні бібліотеки. Навіщо це потрібно? Ну, наприклад, у залежностях у composer.json ви вказали "symfony/symfony": "~2.5", що означає, що ваш код має працювати з Symfony 2.5, 2.6, 2.7 і т.д., але не з 3.0 і вище. Коли виходить нова мінорна версія, вам, звичайно, може бути все одно, поки ви не отримаєте issue на GitHub, що з новою версією ваш бандл перестав працювати. Ну, а якщо ви альтруїст, то підштовхнете себе, перевірите ваш код на сумісність з новою версією, виправите, що потрібно, і випустите фікс. Користувачі будуть щасливі, навіть самі того не знаючи.

Також якщо ви проганяєте тести через Travis, то можна додати конфіги для тестування на новій версії Symfony, від якої залежить ваш код. Перевірка проєктів на інших мовах також здійснюється через менеджери пакетів. Підтримуються: Composer, Bundler, PIP, NPM, Bower, Leiningen, CocoaPods, Maven, SBT, Gradle. Ще одна фіча цього сервісу — він дозволяє подивитися, скільки інших репозиторіїв вказали ваш як залежність. Головне, щоб вони також були додані в VersionEye. Хіба вам не цікаво, хто і де використовує ваш код? Ось приклад з сторінки Symfony версії 2.6.4.

По кліку на References можна побачити список проєктів, які залежать від Symfony. Цей сервіс надає два бейджики (наводжу бейджики для Symfony):

Їх код можна отримати на сторінці репозиторію в VersionEye, клікнувши на сам бейдж.

Взагалі, цей сервіс мені дуже подобається. Іноді, правда, він спамить, якщо чужі вендори випускають кілька патчів на день, але з цим можна миритися. Головне, що він дає свіжу інформацію.

CodeCov

CodeCov — сервіс, який надає красиві звіти по покриттю вашого коду тестами. Щоб працювати з цим сервісом, потрібно трохи змінити конфіги в файлі .travis.yml. Ось як може виглядати конфіг:

language: php

php:
  - 5.4
  - 5.5
  - 5.6

before_install:
  - sudo pip install codecov

before_script:
  - composer install --dev

script:
  - phpunit --coverage-clover=coverage.xml

after_success:
  - codecov

Додаються секції before_install і after_success, а PHPUnit потрібно запустити з параметром --coverage-clover=coverage.xml. Після прогонки Travis CI з оновленим конфігом повинно пройти деякий час, поки звіт з'явиться у вашому акаунті на CodeCov. На сторінці перегляду статистики вашого репозиторію в пункті меню Features можна знайти код для бейджика, сам він виглядає так:

Ще одна класна фішка CodeCov — це інтерактивний графік комітів з показником code coverage кожного:

Я навів просто картинку, але в інтерактивній версії можна клікати на точки і переходити на звіт по покриттю тестами для конкретного коміту.

Coveralls

Coveralls — сервіс, аналогічний попередньому. Щоб його використовувати, потрібно додати в composer.json:

{"require-dev":{"satooshi/php-coveralls":"dev-master"}}

і змінити конфіг .travis.yml:

language: php

php:
  - 5.4
  - 5.5
  - 5.6

before_script:
  - composer install --dev

script:
  - phpunit --coverage-clover build/logs/clover.xml

after_script:
  - php vendor/bin/coveralls -v 

PHPUnit потрібно запустити з опцією --coverage-clover build/logs/clover.xml, і вказати в after_script, що після його виконання потрібно виконати скрипт coveralls, який передасть файл звіту на сервер Coveralls. Перед цим також не забудьте в своєму дашборді в Coveralls підключити ваш репозиторій з GitHub.

Моя особиста думка, що в цілому цей сервіс красивіше показує звіти по code coverage. Не бачу сенсу використовувати Coveralls і CodeCov одночасно, можете спробувати обидва і вибрати на свій смак.

Gitter

Сервіс Gitter нещодавно запустився і представляє собою чат для GitHub. Для кожного репозиторію на GitHub можна створити окремий публічний чат. Річ хороша, адже не все і не завжди хочеться обговорювати через пулл-реквести. Іноді хочеться пофлудити ^_^ або задати питання великій кількості людей і отримати швидку відповідь. Обмеження безкоштовної версії в тому, що історія повідомлень буде зберігатися максимум два тижні, і можна створити лише один приватний чат на організацію, створену в GitHub. Бейдж виглядає так:

А знайти його код можна на сторінці каналу:

Наскільки популярною буде безкоштовна версія, поки що сказати складно. Давши одного разу відповідь на непросте питання, через два тижні його вже ніхто не побачить. Тому поки не ясно, приживеться чи цей сервіс, хоча і активно використовується. Користуючись нагодою, наводжу посилання на чати PHP-спільноти України:

• https://gitter.im/php-ua/php
• https://gitter.im/php-ua/symfony
• https://gitter.im/php-ua/zf
• https://gitter.im/php-ua/yii
• https://gitter.im/php-ua/laravel
• https://gitter.im/php-ua/phalcon

CoderWall

CoderWall — це щось на кшталт соціальної мережі (якщо це можна так назвати) для програмістів. Можна ділитися порадами, створювати профілі організацій, додавати туди учасників, додавати вакансії, слідкувати за користувачами. Цей сервіс також надає можливість отримати бейджики. Але ці бейджики будуть додаватися до вашого профілю на GitHub, а не до конкретного репозиторію.

Для того, щоб отримати бейдж, потрібно додати свій навик у профіль, наприклад: php, open source. Головне — правильно написати назву технології, якщо сумніваєтеся — подивіться профілі інших учасників, як написано у них. Далі раз на тиждень (інформація з сайту) сервіс співвідносить ваші навики з профілю з вашою діяльністю на GitHub. Якщо ви вказали навик PHP і у вас є репозиторій на GitHub, в якому основна мова програмування — це PHP, тоді ви отримаєте бейджик «павук». За три PHP-репозиторії — ви отримаєте бейдж «подвійний павук». Але ці бейджики поки що будуть видні тільки на сторінці вашого профілю в CoderWall. Щоб вони були видні на GitHub, потрібно підключити свій GitHub-акаунт у профіль CoderWall. Через деякий час CoderWall запросить вас у свою організацію, і ви отримаєте бейдж на GitHub. Ось приклад бейджиків з мого профілю.

Кому цікаво - вихідний код CoderWall доступний на GitHub, сам сайт написаний на Ruby. Ось приклад профілю команди GitHub.

SensioLabs Insight

Дуже люблю компанію SensioLabs за те, що вона розробляє корисні речі для світу PHP. SensioLabs Insight — ще один сервіс для аналізу коду, але тільки PHP. Точніше, не тільки PHP, там є можливість вказати, що саме знаходиться у вашому репозиторії: Symfony-бандл, Symfony-проект, модуль для Drupal тощо.

В залежності від типу репозиторію, Insight додатково перевірить конфіги в XML та YAML файлах, Twig шаблони, залежності композера.

Список проблем, які перевіряє SensioLabs Insight, просто вражаючий. І синтаксичні помилки, і інструкції, які можуть зробити ваш код небезпечним, і використання версій бібліотек, в яких є відома уразливість, і ще безліч всього. Загалом проводиться більше сотні різних перевірок. Внаслідок перевірок ваш код може отримати медаль за відвагу!!! Якби код був живою істотою, то він би подякував свого творцеві :)

Медалі залежать від кількості помилок. Поки у вас хоч одне критичне зауваження — медалі вам не видати! Медалі-бейджики бувають трьох розмірів, обирайте, який вам більше подобається:

Отримати код для будь-якого вашого репозиторію, підключеного до SensioLabs Insight, можна на сторінці вашого акаунта. Також можна налаштувати автоматичну перевірку ваших репозиторіїв на GitHub через web-hook. Адреса, яка повинна запустити GitHub, щоб розпочати чергову перевірку, береться на сторінці API/SDK вашого акаунта. Після чого заходьте в налаштування вашого репозиторію на GitHub у меню Webhooks & Services і створюєте новий хук.

Однозначно використовуйте цей сервіс! Він знайде у вашому коді те, про що ви навіть не підозрювали. Безкоштовна версія доступна для публічних репозиторіїв, приватність, звичайно, вже платна.

KnpBundles

Якщо ви Symfony-розробник, то, звичайно, знаєте про сайт knpbundles.com. На цьому сайті зібрані популярні бандли для Symfony2. Якщо ви розробили бандл і хочете, щоб він там з'явився, то вам доведеться зробити це самостійно. Увійдіть за допомогою GitHub і додайте посилання на ваш репозиторій. Тобто, якщо ви не хочете публікувати свій бандл на сайті, то він там не з'явиться! На цьому сайті існує система рейтингу. Оцінка для бандла нараховується так:

• 1 бал за кожного фоловера на GitHub;
• 5 балів за README файл, якщо в ньому більше ніж 300 символів;
• 5 балів, якщо бандл підключений до Travis CI;
• Ще 5 балів надається за останній успішний билд на Travis CI;
• 5 балів, якщо в бандлі є файл composer.json і репозиторій додано на packagist.org;
• 5 балів за кожну рекомендацію бандла на сайті knpbundles.com (рекомендувати можуть тільки зареєстровані користувачі сайту).
• Бонус за активність за останні 30 днів. Формула (30 — кількість днів з останньої активності) / 5. Мінусові значення не враховуються, але можуть бути дробові значення.

Як бачимо, не так вже й багато балів може набрати бандл завдяки зусиллям лише одного автора. Левову частку балів додають фолловери та рекомендатели. Бандл має бути дійсно потрібним і якісним, щоб у користувача виникло бажання поставити йому плюс.

Сайт надає два види бейджиків (їх код можна знайти на сторінці бандла в сайдбарі). Для прикладу візьмемо найпопулярніший бандл FOSUserBundle та його варіанти бейджиків:

Мої рекомендації: однозначно додайте свій бандл на цей сайт і вставте код бейджика. Адже якщо ви його виставили в open source, значить хочете, щоб ним користувалися. Розкажіть про нього спільноті!

HHVM

Якщо ви хочете перевірити свій код на сумісність з HHVM, вам потрібно додати кілька рядків у .travis.yml, це можна зробити ось так:

language: php

php:
  - 5.3
  - 5.4
  - 5.5
  - 5.6
  - hhvm

matrix:
  allow_failures:
    - php: hhvm

before_script:
  - composer install --dev

script:
  - phpunit --coverage-text tests

Потрібно додати --hhvm у версії PHP. Якщо ваш код не може виконатися на HHVM, то збірка буде позначена як провалена. Якщо ви хочете просто моніторити сумісність з HHVM, але при цьому не фейлити білд, то потрібно додати опцію allow_failures. Бейджик, який буде показувати підтримку HHVM, можна взяти на сайті https://hhvm.h4cc.de/.

На сторінці Search знаходимо потрібний репозиторій з гітхаба, одразу бачимо перевірку на сумісність кожної версії, клікаємо на Badges і отримуємо потрібний код.

Shields.io

Shields.io — сайт, на якому бейджики від різних сервісів приведені до одного стандартного вигляду. Список досить великий, тут зібрані найпопулярніші сервіси для різних мов програмування. Я нещодавно дізнався про цей збірник, і він мені одразу сподобався. Є три шаблони бейджиків:

Особисто мені дуже сподобався останній, і я змінив усі бейджики в одному з моїх репозиторіїв.

Було:

Стало

Щоб отримати код у форматі Markdown, потрібно клікнути на бейджі зі списку. Єдиний мінус — що прописувати шлях до свого репозиторію на потрібному сервісі доведеться самому. Іноді потрібно просто вказати нік і назву репозиторію. А іноді, натомість, потрібно вказати хеш-код, наприклад, https://img.shields.io/sensiolabs/i/45afb680-d4e6-4e66-93ea-bcfa79eb8a87.svg. У такому випадку потрібно йти в особистий кабінет і там шукати...

Висновок

Звичайно, список не повний. Ще є безліч різних сторонніх сервісів для інших мов програмування, навіть для PHP, думаю, знайдеться ще парочка рішень, про які я не знав. Але тут справа така, за всім не встежиш. Останнім часом спостерігається бум подібних сервісів, і їхня популярність серед розробників зростає. Сподіваюся, після цієї статті вона ще трохи збільшиться :). Не нехтуйте сервісами, які розроблені, щоб вам допомагати!