Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
207 lines (135 loc) · 9.95 KB

CONTRIBUTING.md

File metadata and controls

207 lines (135 loc) · 9.95 KB

Contributing

Процесс внесения изменений в репозиторий

Node, npm versions

Для корректной работы, необходимо использовать:

  • Node lts/hydrogen -> v18.16.*;
  • npm ^8.19.0 или ^9.5.1;

Для этого нужно выполнить команду в корне репозитория:

 nvm use

Разработка с помощью Lerna

Для внесения правок в нескольких пакетах одновременно, можно выполнить следующие команды в корне проекта:

Установить все зависимости и слинковать все пакеты:

npx lerna bootstrap

Установить и слинковать все зависимости только у указанного пакета:

npx lerna bootstrap --scope [имя пакета 1] --include-dependencies

Установить и слинковать только указанные зависимости:

npx lerna bootstrap --scope [имя пакета 1] --scope [имя пакета 2]

Если возникла какая-либо проблема со сборкой, можно попробовать полностью удалить все зависимости и установить их заново:

rm -rf ./node_modules/
npm ci
npx lerna clean -y
npx lerna bootstrap

Запуск Storybook

Для разработки компонент используется Storybook, который запускается и собирается с помощью Vite. Для локальной разработки необходимо из корня проекта перейти в нужную директорию (plasma-web, plasma-b2c, plasma-ui) и выполнить команду запуска:

cd plasma-web/
npm run storybook

Обновление API

Если в процессе разработки были затронуты библиотеки plasma-b2c, plasma-web, plasma-hope или plasma-core, необходимо обновить API компонент, которые лежат в директориях api/*.md. Для этого нужно (важно, чтобы пакеты при этом были слинкованы) выполнить команду генерации в корне проекта и сгенерированные файлы добавить отдельным коммитом:

npm run api:report

Если вы делали изменения в библиотеках и не обновляли API, то пре-коммит хук husky не даст вам запушить, и запустит этот скрипт самостоятельно.

Если вы пушите с флагом --no-verify, и у вас есть не закоммиченные изменения, то сборка упадет на шаге release.

Issues

Если в процессе разработки выяснилось, что необходимо сделать какое-то изменение в будущем или встретился какой-либо баг, то требуется создать новый Issue, добавить в нём описание и требования, а также отметить данный участок кода комментарием с ключевым словом TODO и ссылкой на ишью:

// TODO: https://github.com/salute-developers/plasma/issues/438

Cypress тесты

Хорошим тоном является добавление новых тест-кейсов, если был обновлён / исправлен функционал компонента или его визуальная составляющая.

Для этого необходимо наличие установленных приложений:

  • Cypress (из команды npm ci)
  • Docker
  • chromium

Примечание

Все UI тесты запускаются в chromium. Поэтому убедитесь в его локальном наличии.

brew install chromium --no-quarantine

На примере пакета @salutejs/plasma-ui работа с тестами выглядит следующим образом:

  • если Docker не установлен, установите его;
  • убедитесь, что докер запущен;
  • необходимо установить все пакеты в monorepo, для этого в корне выполните команды:
npm ci && npx lerna bootstrap

Запуск тестов

В корне monorepo выполните команду (для остальных библиотек команды будут соответствующими):

npm run cy:ui:run

Обновление скриншотов

Если это необходимо, то для этого выполните команду:

npm run cy:ui:update
  • добавьте их в commit;

Отладка тестов

Выполните команду:

npm run cy:ui:open

Запуск тестов с указанием компонента(-ов)

По умолчанию тесты запускаются для всего имеющегося набора.

Это поведение можно изменить указав что именно нужно запускать.

npm run cy:ui:run --components='component1, component2'

или

npm run cy:web:update --components='component1, component2'

Commit step

Мы используем Conventional Commits (https://www.conventionalcommits.org/). Git commit message должен быть на английском языке. Изменения в коммите должны затрагивать только один пакет. Версионирование пакетов происходит автоматически, руками версию в package.json не поднимаем.

Пример коммита в пакет @salutejs/plasma-ui:

git commit -m "feat(plasma-ui): Component X added"

Пример 2:

git commit -m "fix(plasma-web): Fix component Y"

Использование Conventional Commits обязательно:

  • fix - если вносится исправление в существующую функциональность. Приведет к выпуску патча пакета по semver;
  • feat - если в кодовую базу добавляется новая функциональность. Приведет к выпуску минорной версии пакета;
  • docs - если вносится изменение в контент документации, например в файлах с расширениями *.md и *.mdx;
  • chore - если вносимые изменения не относятся ни к кодовой базе пакетов, ни к документации;
  • build - сборка пакетов и утилит;
  • test - для добавления / обновления тестов и снапшотов;
  • ci - для всех коммитов в папке .github

Pull request

  • Создаем PR в ветку dev, дожидаемся успешного завершения работы CI. Если последний commit-message содержит [skip ci] - CI запущен не будет.
  • По завершению должны выпуститься canary-версии затронутых пакетов.
  • Дописываем в главный коммент описание того, что было сделано и для чего.
  • Дожидаемся аппрува от всех ревьюеров ПРа.
  • Добавляем PR в очередь на мёрж.

Release

Все PR производятся в ветку dev, ветка dev периодически вливается в ветку master и происходит выпуск изменений в затронутых пакетах. После влития выполняется ряд github actions. После успешного завершения работы CI для каждого затронутого пакета будет:

  • Поднята версия
  • Собран CHANGELOG.md (+ общий для всего монорепозитория)
  • Выпущена новая версия в npm-registry
  • Получен положительный результат после проведения тестов
  • Собрана документация и Storybook's.
  • В репозитории будут проставлены соответсвующее теги и влиты созданные CHANGELOG.md и обновления package.json

После этого ветка dev отводится заново.

HotFix

В случае обнаружения критичных багов, необходимо сделать два PR — один в ветку dev, другой в ветку master, влитие пулл-реквеста в master приведет к выпуску релиза описанного ранее, при этом ветка dev остается не влитой, в релиз попадает только изменения из hotfix.

Релизный процесс

Релизный процесс представлен на следующем изображении:

plasma