# Contributing
Процесс внесения изменений в репозиторий
## Node, npm versions
Для корректной работы, необходимо использовать:
- **Node** из `.nvmrc`;
- **npm** из поставки Node;
Для этого нужно выполнить команду в корне репозитория:
```sh
nvm use
```
## Установка зависимостей
Для внесения правок в нескольких пакетах одновременно, можно выполнить следующие команды в корне проекта:
Установить все зависимости, применить патчи и собрать workspace-пакеты:
```sh
npm run setup
```
Установка выполняется на уровне корня monorepo. Фильтрацию по пакетам нужно применять на уровне запуска команд:
```sh
npx lerna run [команда] --scope [имя пакета 1] --include-dependencies
```
Если возникла какая-либо проблема со сборкой, можно попробовать полностью удалить все зависимости и установить их заново:
```sh
rm -rf ./node_modules/
npm run setup
```
## Обновление package-lock.json
При изменении `dependencies`, `devDependencies` или `peerDependencies` в корневом или пакетном `package.json` необходимо синхронизировать lock-файлы.
**Рекомендуемый способ (полная регенерация, как в CI):**
```sh
npm install --no-audit --no-progress --package-lock-only --ignore-scripts
```
**Не делайте так:**
- `cd packages/foo && npm install` — изолированная установка перегенерирует lock и может изменить дерево зависимостей;
- `npm install --package-lock-only` без флагов, используемых в рекомендуемой команде;
- форматирование `package-lock.json` через Prettier — lock-файлы генерируются npm.
Проверка: `git diff` по lock-файлам должен отражать только изменения зависимостей, а не массовую смену отступов.
## Запуск Storybook
Для разработки компонент используется `Storybook`, который запускается и собирается с помощью `Vite`. Для локальной разработки необходимо из корня проекта перейти в нужную директорию (`plasma-web`, `plasma-b2c`) и выполнить команду запуска:
```sh
cd plasma-web/
npm run storybook
```
## Обновление API
Если в процессе разработки были затронуты библиотеки `plasma-b2c`, `plasma-web`, `plasma-hope` или `plasma-core`, необходимо обновить API компонент, которые лежат в директориях `api/*.md`. Для этого нужно (важно, чтобы пакеты при этом были слинкованы) выполнить команду генерации в корне проекта и сгенерированные файлы добавить отдельным коммитом:
```sh
npm run api:report
```
Если вы делали изменения в библиотеках и не обновляли API, то пре-коммит хук `husky` не даст вам запушить, и запустит этот скрипт самостоятельно.
Если вы пушите с флагом `--no-verify`, и у вас есть не закоммиченные изменения, то сборка упадет на шаге `release`.
## Issues
Если в процессе разработки выяснилось, что необходимо сделать какое-то изменение в будущем или встретился какой-либо баг, то требуется создать новый [Issue](https://github.com/salute-developers/plasma/issues), добавить в нём описание и требования, а также отметить данный участок кода комментарием с ключевым словом `TODO` и ссылкой на ишью:
```javascript
// TODO: https://github.com/salute-developers/plasma/issues/438
```
## Cypress тесты
Хорошим тоном является добавление новых тест-кейсов, если был обновлён / исправлен функционал компонента или его визуальная составляющая.
Для этого необходимо наличие установленных приложений:
- `Cypress` (из команды `npm ci`)
- `Docker`
- `chromium`
#### Примечание
Все UI тесты запускаются в `chromium`. Поэтому убедитесь в его локальном наличии.
```bash
brew install chromium --no-quarantine
```
На примере пакета `@salutejs/plasma-web` работа с тестами выглядит следующим образом:
- если `Docker` не установлен, установите его;
- убедитесь, что докер запущен;
- необходимо установить все пакеты в **monorepo**, для этого в корне выполните команды:
```sh
npm ci
```
#### Запуск тестов
В корне **monorepo** выполните команду (для остальных библиотек команды будут соответствующими):
```sh
npm run cy:web:run
```
#### Обновление скриншотов
Если это необходимо, то для этого выполните команду:
```sh
npm run cy:web:update
```
- добавьте их в commit;
#### Отладка тестов
Выполните команду:
```sh
npm run cy:web:open
```
#### Запуск тестов с указанием компонента(-ов)
По умолчанию тесты запускаются для всего имеющегося набора.
Это поведение можно изменить указав что именно нужно запускать.
```sh
npm run cy:web:run --components='component1, component2'
```
или
```sh
npm run cy:web:update --components='component1, component2'
```
## Commit step
Мы используем Conventional Commits (). Git commit message должен быть на английском языке.
Изменения в коммите должны затрагивать только один пакет.
Версионирование пакетов происходит автоматически, руками версию в `package.json` не поднимаем.
```sh
git commit -m "fix(plasma-web): Fix component Y"
```
Использование Conventional Commits обязательно:
- `fix` - если вносится исправление в существующую функциональность. Приведет к выпуску _патча_ пакета по [semver](https://semver.org/lang/ru/);
- `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`.
### Релизный процесс
Релизный процесс представлен на следующем изображении:
