studio/docs/ONBOARDING.md

Onboarding нового разработчика — путь от нуля до первого PR

Этот документ — пошаговый сценарий первого дня нового контрибьютора Рублокса. От «никогда не видел проект» до «мой PR смержили».

Время — ~2-3 часа при хорошей сети.

---

Что мы делаем

Тебе предстоит:

1. Создать аккаунт в Майнкрафтии (если ещё нет).
2. Получить роль developer от Лида.
3. Зайти в /developer на team.rublox.pro — это твой dashboard контрибьютора.
4. Подписать CLA (Contributor License Agreement, одна кнопка).
5. Добавить SSH-ключ в Gitea.
6. Склонировать репо (player или studio).
7. Поднять локальное окружение (npm install + dev-сервер).
8. Открыть staging для тестов с реальными данными.
9. Сделать ветку, изменения, коммит, push, открыть PR.
10. Получить ревью и (после правок если нужно) — merge.

---

Шаг 1. Аккаунт в Майнкрафтии

Если ещё нет:

1. Зайди на https://minecraftia-school.ru/
2. Жми «Регистрация», заполняй (email, пароль, имя).
3. Подтверди email через ссылку в письме (или через Яндекс OAuth).

Запиши свой email и числовой user_id — он будет нужен дальше. Найти его можно так: открой свой профиль (/profile), там в URL будет id.

---

Шаг 2. Получить роль developer

Только Лид (МИН) может выдать эту роль. Напиши ему в команде, дай свой user_id. Он выполнит:

POST https://team.rublox.pro/api-team/developer/grant/<твой_uid>

После этого в team-flask твой team_roles_extra будет содержать developer, и у тебя появится доступ к /developer.

Как проверить: зайди на https://team.rublox.pro/ — в сайдбаре должен появиться пункт «Разработка». Если нет — роль не выдана.

---

Шаг 3. Зайти в /developer (твой dashboard)

URL: https://team.rublox.pro/developer

Что увидишь — 7 вкладок:

Вкладка	Что в ней
Обзор	Твоя статистика (PR, merged, score) + открытые PR команды + последние коммиты
Pull Requests	Все открытые PR в org rublox, можно фильтровать
Коммиты	Последние 50 коммитов по всем репо
Репозитории	Карточки rublox/player + rublox/studio с командой git clone
Топ	Лидерборд разработчиков по score
SSH-ключи	Управление твоими SSH-ключами в Gitea
CLA	Статус подписи Contributor License Agreement

---

Шаг 4. Подписать CLA

CLA — это юридическое соглашение что ты передаёшь Рублоксу права на свой код (стандартная opensource-практика, как у Google CLA).

1. Открой вкладку «CLA».
2. Прочитай текст соглашения.
3. Жми «Подписать».

В БД создастся запись team_cla_signatures (user_id, version, signed_at, ip, ua) — это и есть твоя подпись.

Без CLA твои PR смержить нельзя. Это технически возможно (Gitea пропустит), но юридически — нет.

---

Шаг 5. Добавить SSH-ключ в Gitea

Чтобы делать git push без ввода пароля.

5.1. Сгенерируй ключ (если нет)

В терминале:

ssh-keygen -t ed25519 -C "твой_email@example.com"

Жми Enter на все вопросы (без passphrase для простоты). Получится пара файлов:

• ~/.ssh/id_ed25519 — приватный (НИКОМУ не показывай)
• ~/.ssh/id_ed25519.pub — публичный (его и загружаем)

5.2. Скопируй публичный ключ

cat ~/.ssh/id_ed25519.pub

Скопируй вывод целиком (начинается с ssh-ed25519 AAAA...).

5.3. Добавь в Gitea

В /developer открой вкладку «SSH-ключи» → жми «Добавить ключ» → вставь публичный ключ → название («Мой ноут»).

Это под капотом дёрнет Gitea admin API и привяжет ключ к твоему аккаунту в git.rublox.pro.

5.4. Проверь

ssh -T git@git.rublox.pro -p 2222

Должен ответить Hi <твой_логин>!. Если ругается на permission denied — ключ не привязался, проверь шаг 5.3.

---

Шаг 6. Склонировать репо

В /developer вкладка «Репозитории» — выбери что хочешь:

Player (веб-плеер, что юзеры открывают для игры)

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

Studio (редактор где создаются игры)

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

Что выбрать первым: если ты frontend-разработчик React, и хочешь начать с чего-то проще — бери player (он меньше, ~50К строк). Studio тяжелее (~80К + Babylon-движок).

---

Шаг 7. Поднять локальное окружение

7.1. Требования

• Node.js 20+ (nodejs.org)
• npm 10+ (идёт с Node)
• Git (git-scm.com)
• IDE — рекомендую VS Code

Проверка:

node --version   # должно быть v20.x.x или выше
npm --version    # должно быть 10.x.x или выше

7.2. Установить зависимости

npm install

Это займёт 2-5 минут. Скачает Babylon.js, React, Vite и ~200 других пакетов в node_modules/.

7.3. Запустить dev-сервер

npm run dev

Vite запустит локальный сервер:

• player — http://localhost:5173
• studio — http://localhost:5174

Открой URL в браузере — увидишь свою локальную копию.

Как работает API в dev-режиме: Vite автоматически проксирует все /api-* запросы на staging-окружение https://dev-api.rublox.pro/ (это копия прод-БД с анонимизированными юзерами). То есть твоя локальная копия будет ходить на staging — никаких проблем с CORS, никаких опасностей задеть прод.

---

Шаг 8. Аутентификация в dev-режиме

Локально у тебя нет JWT — окно регистрации/логина откроется.

Два варианта:

Вариант A — сделать тестовый аккаунт прямо на staging

Зарегистрируйся на dev-api.rublox.pro как новый юзер (или используй один из 2487 анонимизированных, чьи пароли все сброшены на test123). У этих юзеров уже есть тестовые проекты в БД.

Вариант B — STANDALONE-режим (без бэка)

Создай файл .env.local в корне репо:

VITE_STANDALONE=true

И перезапусти npm run dev. Студия/плеер запустятся в режиме «гость» — все API-запросы замокированы, можно тестировать UI без реальных данных.

---

Шаг 9. Сделать первое изменение

Для тренировки — измени какой-нибудь видимый текст или цвет.

9.1. Создай ветку

git checkout -b fix/typo-on-homepage

Соглашение по именам:

• feature/<short-name> — новая фича
• fix/<short-name> — багфикс
• chore/<short-name> — рефакторинг, документация

9.2. Сделай изменение

Открой файл в IDE, измени что-нибудь.

Пример (для studio): открой src/community/KubikonStudio.jsx, найди строку 'Создавай большие игры', замени на что-нибудь. Сохрани — Vite сделает HMR и ты увидишь изменение в браузере мгновенно.

9.3. Проверь свой код

npm run lint          # ESLint — проверка стиля
npm run format:check  # Prettier — проверка форматирования
npm run build         # Сборка должна пройти

Если что-то ругается — поправь.

9.4. Закоммить

git add .
git commit -m "fix: typo on homepage"

Формат commit message — Conventional Commits:

• feat: добавил кнопку X
• fix: исправил Y
• chore: рефакторинг Z
• docs: обновил README

9.5. Запушь

git push -u origin fix/typo-on-homepage

Gitea ответит:

remote: Create a new pull request for 'fix/typo-on-homepage':
remote:   https://git.rublox.pro/rublox/studio/compare/main...fix/typo-on-homepage

---

Шаг 10. Открыть Pull Request

10.1. Перейти по ссылке

Открой URL из вывода git push, ИЛИ зайди на https://git.rublox.pro/rublox/studio → жми «Pull Requests» → «New Pull Request».

10.2. Заполнить PR

Title: одна строка, на русском, описывает что сделано

• ✅ «fix: опечатка на главной странице студии»
• ❌ «исправление»

Description: что и зачем, можно добавить скриншот «до/после». Шаблон:

## Что сделано
Исправил опечатку «Создавай большие иры» → «Создавай большие игры».

## Зачем
Юзеры жаловались, выглядит непрофессионально.

## Как проверить
1. Открой главную студии
2. В hero-баннере смотри заголовок
3. Должно быть «игры», не «иры»

10.3. Жми «Create Pull Request»

Сразу после создания запустится CI в Gitea Actions:

• lint — ESLint без warnings
• format-check — Prettier
• build — vite build проходит
• secret-scan — trufflehog не нашёл утечек секретов
• size-check — PR не больше 1000 строк (warning)

Жди ~3-5 минут пока зелёные галочки появятся. Если красная — открой лог, поправь, git commit --amend && git push -f или новым коммитом.

10.4. Жди ревью

В /developer → Pull Requests твой PR появится в списке. Кто-то из core-команды его посмотрит, оставит комментарии или сразу одобрит.

Если будут замечания — внеси правки, закоммить, запушь. PR автоматически обновится.

10.5. Merge

Когда CI зелёный и ревьюер одобрил — Лид нажмёт «Merge».

После merge:

• Твои метрики обновятся: prs_merged += 1, score += 5.
• Ты появишься в «Топе» лидерборда (если ещё нет).
• На staging автоматически уйдёт твой код (через ~5 минут — CD не настроен, ручной редеплой).

---

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

После первого merged PR — погружайся глубже:

• ARCHITECTURE.md — как устроена студия архитектурно
• src/editor/engine/README.md — движок Babylon
• TUTORIAL_ADD_BLOCK.md — добавить новый тип блока
• TUTORIAL_DEBUG_BABYLON.md — отладка 3D-сцены
• API_USAGE.md — какие эндпоинты бэкенда мы дёргаем

Куда обращаться за помощью

• Канал #разработка в https://team.rublox.pro — главное место для вопросов
• Issues в Gitea — https://git.rublox.pro/rublox/studio/issues — для багов/предложений
• Лид (МИН) — последняя инстанция, пингуй если ничего не работает

---

Чек-лист готовности

Перед тем как считать что освоился:

• Аккаунт в Майнкрафтии
• Роль developer от Лида
• CLA подписан
• SSH-ключ в Gitea, ssh -T git@git.rublox.pro -p 2222 работает
• Репо склонирован, npm install прошёл
• npm run dev запустил, открыл http://localhost:5173 (или 5174)
• Залогинился в локальную копию
• Сделал тестовое изменение, увидел через HMR
• Запушил, открыл PR, CI зелёный, merge получил

Прошёл всё — поздравляю, ты в команде. Дальше — выбирай задачу из issues и поехали.