@hh.ru/bloko NPM

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);

```json
{
    "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-<версия>

После этого пишем письмо на 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я стилизация медиа-выражениями или изменение стиля/логики работы модами, такие ситуации обсуждаются отдельно.