player/docs/TUTORIAL_FIRST_PR.md

Туториал: твой первый 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 минуты)

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

Если ssh не работает (нет ключа в Gitea) — используй HTTPS:

git clone https://git.rublox.pro/rublox/player.git

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

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

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

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

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, найди:

{"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: Проверь стиль кода

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

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

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

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 — как устроен плеер изнутри
• CONTRIBUTING.md — детально про стиль и процесс
• SECURITY.md — что делать если нашёл уязвимость
• TUTORIAL_DEBUG_BABYLON.md — отладка 3D-сцены
• 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.