МАЖОРНАЯ версия — когда сделаны обратно несовместимые изменения 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-<версия>

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

FAQs

What is @hh.ru/bloko?

Is @hh.ru/bloko well maintained?

Package last updated on 29 Jan 2025

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

@hh.ru/bloko

Содержание:

Версионирование bloko