# Contributing

Руководство для контрибьюторов проекта **@fozy-labs/rx-toolkit**.

## Содержание

- [Contributing](#contributing)
  - [Содержание](#содержание)
  - [Быстрый старт](#быстрый-старт)
  - [Структура проекта](#структура-проекта)
  - [Разработка](#разработка)
    - [Исходный код (`src/`)](#исходный-код-src)
    - [Интерактивные примеры (`apps/demos/`)](#интерактивные-примеры-appsdemos)
    - [Документация (`docs/`)](#документация-docs)
  - [Тесты](#тесты)
  - [Инструменты разработки](#инструменты-разработки)
  - [Соглашения](#соглашения)
    - [Именование файлов](#именование-файлов)
    - [Протокол сигналов](#протокол-сигналов)
    - [Код и документация](#код-и-документация)
    - [Коммиты](#коммиты)
    - [CHANGELOG](#changelog)
    - [index.ts](#indexts)
  - [AI-assisted разработка](#ai-assisted-разработка)
  - [Релиз](#релиз)


## Быстрый старт

```bash
# Клонирование
git clone https://github.com/fozy-labs/rx-toolkit.git
cd rx-toolkit

# Установка зависимостей
pnpm install

# Проверка типов
pnpm run ts-check

# Запуск тестов
pnpm run test

# Сборка
pnpm run build
```


## Структура проекта

```
rx-toolkit/
├── .github/              # AI-промпты, инструкции, скиллы
├── src/                  # Исходный код библиотеки
│   ├── signals/          # Реактивные примитивы (Signal, Computed, Effect)
│   ├── query/            # Кеш-менеджер (Resource, Command)
│   └── common/           # Утилиты, devtools, React-хуки
├── apps/
│   └── demos/            # Интерактивные примеры (React + Vite + MDX)
├── docs/                 # Документация
└── dist/                 # Результат сборки (не коммитится)
```


## Разработка

### Исходный код (`src/`)

Библиотека состоит из трёх "модулей":

| Модуль | Путь | Описание                                                            |
|--------|------|---------------------------------------------------------------------|
| **Signals** | `src/signals/` | Реактивные примитивы: `State`, `Computed`, `Effect`, операторы и тд |
| **Query** | `src/query/` | Кеш-менеджер: `Resource`, `Command`, агенты, `SKIP_TOKEN` и тд      |
| **Common** | `src/common/` | Общие утилиты, интеграция с DevTools, React-хуки и тд                 |

> **Алиас путей:** `@/` → `src/`.


### Интерактивные примеры (`apps/demos/`)

Демо-приложение на **React 19 + Vite + MDX + Tailwind CSS + HeroUI**.
Примеры можно запускать и редактировать прямо в браузере благодаря `react-live`.

```bash
cd apps/demos
pnpm install
pnpm run dev           # http://localhost:3000
```


**Структура примеров:**

```
apps/demos/src/
├── pages/             # MDX-страницы (SignalsPage, QueriesPage, HomePage)
├── examples/
│   ├── signals/       # Примеры для сигналов
│   └── query/         # Примеры для query
├── components/        # LiveExample, QueryTabs и другие компоненты
└── utils/             # Утилиты для fetch-запросов
```

> При изменении кода в `src/` рассмотрите необходимость добавления интерактивного примера в `apps/demos/`.


### Документация (`docs/`)

Документация на **русском языке**:

| Файл                   | Содержание                     |
|------------------------|--------------------------------|
| `docs/signals/`        | Реактивные примитивы           |
| `docs/query/`          | Query кеш-менеджер             |
| `docs/usage/react/`    | React-хуки                     |
| `docs/devtools/`       | Интеграция с Redux DevTools    |
| `docs/options/`        | Глобальные настройки           |
| `docs/migrations/`     | Гайды миграции между версиями  |
| `docs/contributing/`   | Руководства для контрибьюторов |
| `docs/CHANGELOG.md`    | История изменений              |
| `docs/CONTRIBUTING.md` | Руководство для контрибьюторов |

> При изменении кода в `src/` рассмотрите необходимость обновления соответствующей документации в `docs/`.


## Тесты

Используется **Vitest** с окружением `jsdom`.

```bash
pnpm run test            # Однократный запуск
pnpm run test:watch      # Watch-режим
pnpm run test:coverage   # Отчёт о покрытии
pnpm run test:ui         # Vitest UI в браузере
```

- Тесты размещаются рядом с кодом: `MyModule.test.ts`
- Интеграционные — в `src/__tests__/integration/`


## Инструменты разработки

### Команды

```bash
pnpm run lint           # Проверка линтером (ESLint)
pnpm run lint:fix       # Автоисправление ошибок линтера
pnpm run format         # Форматирование кода (Prettier)
pnpm run format:check   # Проверка форматирования без изменений
```

> `apps/demos/` имеет отдельную конфигурацию ESLint: `cd apps/demos && pnpm exec eslint src/`

### Настройка редактора

Рекомендуемые расширения VS Code:
- **Prettier** (`esbenp.prettier-vscode`)
- **ESLint** (`dbaeumer.vscode-eslint`)

Включите `editor.formatOnSave: true` для автоматического форматирования при сохранении.

### Git blame

Файл `.git-blame-ignore-revs` исключает коммиты массового форматирования из `git blame`. GitHub учитывает его автоматически. Для локальной настройки:

```bash
git config blame.ignoreRevsFile .git-blame-ignore-revs
```


## Соглашения

### Именование файлов

- Классы/типы — **PascalCase**: `Signal.ts`, `ReadonlySignal.ts`
- Фабрики/утилиты — **camelCase**: `createResource.ts`, `deepEqual.ts`
- Типы — суффиксы: `XDefinition`, `XInstance` и тд


### Протокол сигналов

```typescript
signal()       // или signal.get()
signal.peek()  // получить без подписки
signal.set(v)  // установить значение
signal.obs     // RxJS Observable
```


### Код и документация

- Код и комментарии в коде — **на английском**
- Документация (`docs/`) — **на русском**
- AI кастомизация (`.github/`) — **на английском**


### Коммиты

Используются [Conventional Commits](https://www.conventionalcommits.org/), но со следующими адоптациями:
- `chore(..)` (вместо `docs(..)`) - при настройке AI окружения (промпты, инструкции, скиллы и тд)
- `thoughts(..)` (вместо `docs(..)`) - коммиты сгенерированные AI при работе над `.thoughts`


### CHANGELOG

Используется формат [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).

### index.ts

- `src/index.ts` — единственная точка экспорта публичного API.
- `<module>/index.ts` — точка экспорта для конкретного "модуля".


## Релиз

Релизы делятся на:
- **RC** — не стабильные релизы
- **Stable** — стабильные релизы

[//]: # (For humans only guide:)
Инструкция по выпуску описана тут [docs/contributing/release/README.md](contributing/release/README.md).