# Туториал: твой первый Pull Request за 30 минут

Гайд для нового контрибьютора плеера Рублокса. Закончив, у тебя будет смерженный PR и зачисленные баллы разработчика.

## Что нужно перед началом

1. **Аккаунт в Gitea**: войди в https://team.rublox.pro и кликни «Войти через team» в Gitea (https://git.rublox.pro). OAuth создаст тебе профиль с ник = твой `firstName` из team.
2. **Роль `developer`**: попроси Лида выдать через https://team.rublox.pro/developer (или через API `POST /api-team/developer/grant/<твой-uid>`).
3. **CLA подписан**: открой https://team.rublox.pro/developer, вкладка «CLA», кнопка «Я согласен, подписать».
4. **SSH-ключ в Gitea**: вкладка «SSH-ключи». Если ключа нет — создай: `ssh-keygen -t ed25519 -C "твой-email"` и скопируй содержимое `~/.ssh/id_ed25519.pub`.
5. **Node.js 18+**: `node --version` должно показать `v18.x` или выше.

## Шаг 1: Клонируй репо (2 минуты)

```bash
git clone ssh://git@git.rublox.pro:2222/rublox/player.git
cd player
```

Если ssh не работает (нет ключа в Gitea) — используй HTTPS:
```bash
git clone https://git.rublox.pro/rublox/player.git
```

## Шаг 2: Запусти локально (3 минуты)

```bash
npm install                  # ~250 МБ, занимает 1-2 мин
cp .env.example .env         # дефолты подходят
npm run dev
```

Открой http://localhost:5173 — увидишь приветственный экран. Без JWT/ticket'a реальные игры не загрузятся, но мы будем тестить через standalone-режим.

## Шаг 3: Standalone-режим для разработки (1 минута)

```bash
echo "VITE_STANDALONE=true" >> .env
# Перезапусти npm run dev (Ctrl+C → npm run dev снова)
```

Открой http://localhost:5173/sample — загрузится демо-игра из `src/fixtures/sample-game.json`. Игрок-куб на зелёном поле, 4 стены, красная сфера.

## Шаг 4: Сделай маленькое улучшение

Хороший первый PR — что-то маленькое и видимое. Варианты:

- **Опечатка в README** или CHANGELOG (всегда найдётся!).
- **Новый цвет** для одного из примитивов в `src/fixtures/sample-game.json` — поменяй пол с зелёного на красный.
- **Подпись `subText`** в `src/App.jsx:IndexRoute` сделай красивее.

Пример: поменяем цвет пола в sample-game.

Открой `src/fixtures/sample-game.json`, найди:
```json
{"id":"floor","type":"box","x":0,"y":-0.5,"z":0,"sx":20,"sy":1,"sz":20,"color":"#3a8a3a"}
```
Поменяй `#3a8a3a` (зелёный) на свой любимый цвет, например `#7c3aed` (фиолетовый).

Перезагрузи http://localhost:5173/sample — пол стал фиолетовый!

## Шаг 5: Проверь стиль кода

```bash
npm run lint        # ESLint
npm run format      # Prettier (автоформатирует)
```

Оба должны пройти без ошибок. Если ESLint что-то жалуется — исправь.

## Шаг 6: Запушь и открой PR

```bash
git checkout -b feature/cool-floor-color
git add src/fixtures/sample-game.json
git commit -m "feat: фиолетовый пол в sample-game"
git push origin feature/cool-floor-color
```

Перейди по ссылке которую печатает git (или открой https://git.rublox.pro/rublox/player/pulls и кнопка «New Pull Request»). Опиши что и зачем поменял.

## Шаг 7: Дождись CI

После открытия PR автоматически запустятся проверки:
- `Lint + Format` — твой код стилистически чистый
- `Build` — vite build проходит без ошибок
- `Secret scan` — нет утечек паролей/токенов
- `PR size check` — PR не слишком большой

Если что-то падает — исправь, сделай новый commit, запушь — CI перезапустится.

## Шаг 8: Дождись ревью

Лид (МИН) ревьюит каждый PR в течение 48 часов (обычно гораздо быстрее). Если он попросит изменения — поправь, запушь снова в ту же ветку.

После approve Лид сам нажмёт Merge → webhook задеплоит изменения на staging, а тебе зачислятся **+5 баллов разработчика** + бонусы за объём изменений.

## Поздравляем!

Ты сделал первый PR. Дальше — выбирай задачу из issues с тегом `good-first-issue` или предлагай свою.

## Что почитать дальше

- [ARCHITECTURE.md](../ARCHITECTURE.md) — как устроен плеер изнутри
- [CONTRIBUTING.md](../CONTRIBUTING.md) — детально про стиль и процесс
- [SECURITY.md](../SECURITY.md) — что делать если нашёл уязвимость
- [TUTORIAL_DEBUG_BABYLON.md](./TUTORIAL_DEBUG_BABYLON.md) — отладка 3D-сцены
- [TUTORIAL_ADD_SCRIPT_API.md](./TUTORIAL_ADD_SCRIPT_API.md) — как расширить API для игровых скриптов

## Если что-то пошло не так

- **`npm install` упал** — проверь Node.js версию (нужно 18+), удали `node_modules` и `package-lock.json`, запусти заново.
- **Браузер показывает белый экран** — открой DevTools (F12) → Console, увидишь ошибку. Скорее всего сломанный импорт или typo.
- **CI упал** — кликни по красному крестику в PR, увидишь логи. Обычно это format/lint — `npm run format` + `git commit --amend` чинит.
- **Push в Gitea просит пароль** — добавь SSH-ключ в профиль Gitea (см. /developer/keys).

Вопросы — в канал `#разработка` на team.rublox.pro.