@hh.ru/bloko
v183.0.1
Published
hh.ru UI components
Downloads
1,992
Readme
Bloko - Библиотека компонентов hh.ru
Содержание:
- Changelog
- Зависимости
- Установка зависимостей
- Сборка проекта
- Использование bloko в других проектах
- Использование eslint правил блоко в других проектах
- Разработка bloko
- Встроенный сервер для тестирования документации
- Версионирование bloko
- Как собрать релиз bloko
- Как собрать релиз bloko руками
- Как подготовить ветку для тестирования с другим проектом
- Вопросы-ответы
Версионирование bloko
Bloko использует semver.
Версии именуются по шаблону МАЖОРНАЯ
.МИНОРНАЯ
.ПАТЧ
:
МАЖОРНАЯ
версия — когда сделаны обратно несовместимые изменения API.МИНОРНАЯ
версия — когда добавлен новый функционал, не нарушая обратной совместимости.ПАТЧ
-версия — когда сделаны обратно совместимые исправления. Дополнительные обозначения для предрелизных и билд-метаданных возможны как дополнения кМАЖОРНАЯ
.МИНОРНАЯ
.ПАТЧ
формату.
Changelog
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.
Использование bloko в других проектах
Чтобы подключить блоко нужно:
- Добавить зависимость
yarn add @hh.ru/bloko
; - В сборке добавить процессинг для бабеля папки
node_modules/@hh.ru/bloko
; - Подключить raw bloko скрипты (
bloko/raw
) на страницу до остальных скриптов.
Использование eslint правил блоко в других проектах
Для подключения правил из модуля 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"] } }
eslint-baked-rules
Для правила bloko-use-selectable-attributes
генерируется конфиг eslint-rules/baked-rules-config.json
,
собирающий информацию о текущих компонентах.
Он добавляется/обновляется в репозитории автоматически при релизе и необходим для правильной работы правила. В файле хранится мэппинг перечисляемых props к атрибутам компонентов.
При добавлении нового или изменении PropTypes
существующего компонента, можно протестировать правильность генерации этого конфига, выполнив команду gulp eslint-baked-rules
.
Разработка bloko
Любые изменения в репозитории должны проходить под определенной задачей в 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-<версия>
После этого пишем письмо на [email protected] о выходе нового релиза.
Как подготовить ветку для тестирования с другим проектом
Находясь в нужной feature-ветке (например, HH-12345):
yarn push-test-branch
На основе текущей ветки HH-12345 выполняет команду, которая собирает тестовую ветку HH-12345-testing, которая подготовлена к релизу таской prepare-release
и содержит папку build
.
Команда вернет версию блоко вашей ветки, например:
npm-зависимость для проекта:
git+ssh://[email protected]/hhru/bloko.git#35a45e6a99e37461ad472df2f8d26dafb794d6ca
ветка:
HH-12345-testing
Обновить у соответствующего проекта версию bloko:
yarn add git+ssh://[email protected]/hhru/bloko.git#35a45e6a99e37461ad472df2f8d26dafb794d6ca
Вопросы-ответы
Можно ли выпускать несовместимую с одним из клиентов (клиент — проект-пользователь библиотеки) версию? Нужно ли при выпуске bloko для одного клиента тестировать все остальные клиенты и править их или заниматься этим будет тот, кому это понадобится?
Можно выпускать несовместимую версию, не забывая про semver и про то, что в идеале не должно быть обратно несовместимых изменений.
При выпуске bloko тестируется и выпускается только тот клиент, под который сделаны изменения. Остальные клиенты тестируются и переводятся на новую версию теми, кому это понадобится.
Можно ли добавлять в bloko компоненты, использующиеся только одним клиентом? Какие критерии переноса компонента в bloko?
Перед тем, как добавить какой-либо компонент в bloko, нужно посоветоваться с Мишей Калашником.
Если попробовать кратко сформулировать — в bloko уносим всё, что относится к проекту в целом, а не к конкретной странице.
Как быть, если один и тот же компонент захочет выглядеть или работать в разных клиентах по-разному?
bloko ничего не знает про клиентов, использующих библиотеку, поэтому внесение клиенто-зависимой логики в проект не допускается.
В некоторых ситуациях допускаетcя стилизация медиа-выражениями или изменение стиля/логики работы модами, такие ситуации обсуждаются отдельно.