Bloko - Библиотека компонентов hh.ru
- Changelog
- Зависимости
- Установка зависимостей
- Сборка проекта
- Использование bloko в других проектах
- Использование eslint правил блоко в других проектах
- Разработка bloko
- Встроенный сервер для тестирования документации
- Версионирование bloko
- Как собрать релиз bloko
- Как собрать релиз bloko руками
- Как подготовить ветку для тестирования с другим проектом
- Вопросы-ответы
Bloko использует semver.
Версии именуются по шаблону МАЖОРНАЯ
.МИНОРНАЯ
.ПАТЧ
:
-
МАЖОРНАЯ
версия — когда сделаны обратно несовместимые изменения API. -
МИНОРНАЯ
версия — когда добавлен новый функционал, не нарушая обратной совместимости. -
ПАТЧ
-версия — когда сделаны обратно совместимые исправления. Дополнительные обозначения для предрелизных и билд-метаданных возможны как дополнения кМАЖОРНАЯ
.МИНОРНАЯ
.ПАТЧ
формату.
Changelog проекта доступен в CHANGELOG.md
При разработке задачи, в папке changes/
нужно обязательно создать HH-{task}.md
файл с описанием изменений, например: HH-55143.md
.
При сборке релиза содержимое файла будет автоматически добавлено в общий CHANGELOG.md
. Информация о каждом изменении должна начинаться с символа *
, чтобы после добавления в общий CHANGELOG.md
получался список.
Для работы блоко-компонентов требуется:
- Синхронное подключение скрипта
bloko/common/raw/htmlClasses.js
до загрузки стилей. Этот скрипт проставляет в<html>
глобальные классы, которые используются стилями. - Библиотека core-js. Требуется версия не ниже
3.0.0-beta16
, так как нужна поддержкаURL
+UrlSearchParams
дляurlParser
- Для lux компонентов, необходим
react
иreact-dom
Сборщик:
yarn
yarn install
Сборка осуществляется командой:
yarn build
Сборка нужна для запуска юнит тестов и генерирования документации. Для клиентов предполагается использовать несобранный блоко.
Ниже перечислены основные задачи, которые понимает сборщик:
-
yarn build
— создает новую полную сборку библиотеки и документации, запускает все проверки и тесты. Перед каждой новой сборкой предыдущая папкаbuild
удаляется со всем ее содержимым. Данный таск запускает по умолчанию минификацию css, оптимизацию картинок. -
yarn build-watch
— создает новую сборку и затем запускает вотчер. Также вотчится документация lux компонентов и используется hot reload. -
yarn test
— запускает все юнит-тесты. -
yarn clean
— удаляет старую сборку, а именно полностью удаляет папкуbuild
со всем ее содержимым. -
yarn lint
— запуск линтинга. -
yarn jest
— запускает только jest юнит-тесты -
yarn jest -u
— обновляет снепшоты для юнит тестов, которые используют снепшоты -
yarn styleguide
— запускает lux документацию на отдельном порту, автоматически работает hot-reload.
Чтобы подключить блоко нужно:
- Добавить зависимость
yarn add @hh.ru/bloko
; - В сборке добавить процессинг для бабеля папки
node_modules/@hh.ru/bloko
; - Подключить raw bloko скрипты (
bloko/raw
) на страницу до остальных скриптов.
Для подключения правил из модуля eslint-rules
в свой проект нужно:
- Установить плагин eslint-plugin-local-rules:
yarn add eslint-plugin-local-rules
- Создать в корне проекта модуль
./eslint-local-rules.js
, экспортирующий объект с правилами:'use strict'; module.exports = require('@hh.ru/bloko/eslint-rules');
- Добавить плагин
eslint-plugin-local-rules
и указать необходимые правила в конфиг eslint (пример для .eslintrc);{ "plugins": ["local-rules"], "rules": { "local-rules/bloko-no-class-name-literals": ["error"], "local-rules/bloko-use-selectable-attributes": ["error"] } }
Для правила bloko-use-selectable-attributes
генерируется конфиг eslint-rules/baked-rules-config.json
,
собирающий информацию о текущих компонентах.
Он добавляется/обновляется в репозитории автоматически при релизе и необходим для правильной работы правила. В файле хранится мэппинг перечисляемых props к атрибутам компонентов.
При добавлении нового или изменении PropTypes
существующего компонента, можно протестировать правильность генерации этого конфига, выполнив команду gulp eslint-baked-rules
.
Любые изменения в репозитории должны проходить под определенной задачей в jira
.
Обязательна практика создания pull request
для ревью.
yarn storybook
Hornet полностью поддерживает автоматизированную сборку bloko.
Предположим у нас есть ветка HH-12345.
git fetch --tags
git checkout master
git reset --hard origin/master
git merge --no-ff --no-edit HH-12345
yarn install
yarn prepare-release
yarn version --new-version [patch | minor | major] --no-git-tag-version
git add -A
git commit --no-verify -m "release <версия> [ваша.почта@hh.ru]"
git push --tags origin master <версия>
git checkout -b build-<версия>
yarn release
git add -f build
git commit --no-verify -m "build-<версия> build directory"
git push origin build-<версия>
После этого пишем письмо на hh-dev@hh.ru о выходе нового релиза.
Находясь в нужной feature-ветке (например, HH-12345):
yarn push-test-branch
На основе текущей ветки HH-12345 выполняет команду, которая собирает тестовую ветку HH-12345-testing, которая подготовлена к релизу таской prepare-release
и содержит папку build
.
Команда вернет версию блоко вашей ветки, например:
npm-зависимость для проекта:
git+ssh://git@github.com/hhru/bloko.git#35a45e6a99e37461ad472df2f8d26dafb794d6ca
ветка:
HH-12345-testing
Обновить у соответствующего проекта версию bloko:
yarn add git+ssh://git@github.com/hhru/bloko.git#35a45e6a99e37461ad472df2f8d26dafb794d6ca
Можно ли выпускать несовместимую с одним из клиентов (клиент — проект-пользователь библиотеки) версию? Нужно ли при выпуске bloko для одного клиента тестировать все остальные клиенты и править их или заниматься этим будет тот, кому это понадобится?
Можно выпускать несовместимую версию, не забывая про semver и про то, что в идеале не должно быть обратно несовместимых изменений.
При выпуске bloko тестируется и выпускается только тот клиент, под который сделаны изменения. Остальные клиенты тестируются и переводятся на новую версию теми, кому это понадобится.
Можно ли добавлять в bloko компоненты, использующиеся только одним клиентом? Какие критерии переноса компонента в bloko?
Перед тем, как добавить какой-либо компонент в bloko, нужно посоветоваться с Мишей Калашником.
Если попробовать кратко сформулировать — в bloko уносим всё, что относится к проекту в целом, а не к конкретной странице.
Как быть, если один и тот же компонент захочет выглядеть или работать в разных клиентах по-разному?
bloko ничего не знает про клиентов, использующих библиотеку, поэтому внесение клиенто-зависимой логики в проект не допускается.
В некоторых ситуациях допускаетcя стилизация медиа-выражениями или изменение стиля/логики работы модами, такие ситуации обсуждаются отдельно.