МИН
61fba4e174
Большой консолидирующий коммит после поднятия studio.rublox.pro (28 мая 2026). Содержит изменения которые делались в процессе подготовки прод-окружения: Фиксы импортов после выноса из minecraftia: - Массовая замена путей ../../components → ../components (40+ файлов в src/community/, src/admin-preview/) - Замена ../KubikonEditor/ → ../editor/, ../KubikonStudio/ → ../community/, ../AdminPreview/ → ../admin-preview/ - API.js скопирован из минки целиком (было 8 экспортов, стало 312) - Добавлены PLAYER_URL, MyButton_1, недостающие компоненты - Заменены require() на статические ES-imports в BabylonScene, PrimitiveManager, GameRuntime (Vite не поддерживает CJS require) Структура ассетов: - public/kubikon-templates/ → public/assets/kubikon-templates/ - public/kubikon-learn/ → public/assets/kubikon-learn/ - (код искал в /assets/, файлы лежали без /assets/) Навигация роутов внутри студии: - /kubikon-studio/docs → /docs (90+ навигационных вызовов sed-replaced) - /kubikon-editor/X → /edit/X, /kubikon/play/X → /play/X, /kubikon/gd/X → /gd/X UI: - Новый компонент StudioHeader (61px, как в минке) + копия favicon - WithHeader wrapper в App.jsx для всех страниц кроме fullscreen-редактора/плеера - SSO ticket-flow в AuthContext (auto-redeem #ticket= при загрузке) - Тёмная тема карточек игр в ВИКИ (фон #1c2231 вместо #fff, картинка впритык) Документация: - docs/ONBOARDING.md — путь нового контрибьютора от нуля до PR - docs/TUTORIAL_ADD_SCRIPT_API.md — как добавить game.* API - API_USAGE.md — список эндпоинтов backend - README в подпапках engine/, engine/terrain/, engine/voxel/, engine/robloxterrain/, engine/types/ .gitignore: - public/wiki/ исключён (73МБ PNG, будут на CDN отдельной задачей) Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
355 lines
14 KiB
Markdown
355 lines
14 KiB
Markdown
# 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`. Он выполнит:
|
||
|
||
```bash
|
||
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. Сгенерируй ключ (если нет)
|
||
|
||
В терминале:
|
||
|
||
```bash
|
||
ssh-keygen -t ed25519 -C "твой_email@example.com"
|
||
```
|
||
|
||
Жми Enter на все вопросы (без passphrase для простоты). Получится пара файлов:
|
||
- `~/.ssh/id_ed25519` — приватный (НИКОМУ не показывай)
|
||
- `~/.ssh/id_ed25519.pub` — публичный (его и загружаем)
|
||
|
||
### 5.2. Скопируй публичный ключ
|
||
|
||
```bash
|
||
cat ~/.ssh/id_ed25519.pub
|
||
```
|
||
|
||
Скопируй вывод целиком (начинается с `ssh-ed25519 AAAA...`).
|
||
|
||
### 5.3. Добавь в Gitea
|
||
|
||
В /developer открой вкладку **«SSH-ключи»** → жми «Добавить ключ» → вставь публичный ключ → название («Мой ноут»).
|
||
|
||
Это под капотом дёрнет Gitea admin API и привяжет ключ к твоему аккаунту в `git.rublox.pro`.
|
||
|
||
### 5.4. Проверь
|
||
|
||
```bash
|
||
ssh -T git@git.rublox.pro -p 2222
|
||
```
|
||
|
||
Должен ответить `Hi <твой_логин>!`. Если ругается на permission denied — ключ не привязался, проверь шаг 5.3.
|
||
|
||
---
|
||
|
||
## Шаг 6. Склонировать репо
|
||
|
||
В /developer вкладка **«Репозитории»** — выбери что хочешь:
|
||
|
||
### Player (веб-плеер, что юзеры открывают для игры)
|
||
|
||
```bash
|
||
git clone ssh://git@git.rublox.pro:2222/rublox/player.git
|
||
cd player
|
||
```
|
||
|
||
### Studio (редактор где создаются игры)
|
||
|
||
```bash
|
||
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](https://nodejs.org/))
|
||
- **npm 10+** (идёт с Node)
|
||
- **Git** ([git-scm.com](https://git-scm.com/))
|
||
- IDE — рекомендую VS Code
|
||
|
||
Проверка:
|
||
|
||
```bash
|
||
node --version # должно быть v20.x.x или выше
|
||
npm --version # должно быть 10.x.x или выше
|
||
```
|
||
|
||
### 7.2. Установить зависимости
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
Это займёт 2-5 минут. Скачает Babylon.js, React, Vite и ~200 других пакетов в `node_modules/`.
|
||
|
||
### 7.3. Запустить dev-сервер
|
||
|
||
```bash
|
||
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. Создай ветку
|
||
|
||
```bash
|
||
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. Проверь свой код
|
||
|
||
```bash
|
||
npm run lint # ESLint — проверка стиля
|
||
npm run format:check # Prettier — проверка форматирования
|
||
npm run build # Сборка должна пройти
|
||
```
|
||
|
||
Если что-то ругается — поправь.
|
||
|
||
### 9.4. Закоммить
|
||
|
||
```bash
|
||
git add .
|
||
git commit -m "fix: typo on homepage"
|
||
```
|
||
|
||
Формат commit message — **Conventional Commits**:
|
||
- `feat: добавил кнопку X`
|
||
- `fix: исправил Y`
|
||
- `chore: рефакторинг Z`
|
||
- `docs: обновил README`
|
||
|
||
### 9.5. Запушь
|
||
|
||
```bash
|
||
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:** что и зачем, можно добавить скриншот «до/после». Шаблон:
|
||
|
||
```markdown
|
||
## Что сделано
|
||
Исправил опечатку «Создавай большие иры» → «Создавай большие игры».
|
||
|
||
## Зачем
|
||
Юзеры жаловались, выглядит непрофессионально.
|
||
|
||
## Как проверить
|
||
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](../ARCHITECTURE.md) — как устроена студия архитектурно
|
||
- [src/editor/engine/README.md](../src/editor/engine/README.md) — движок Babylon
|
||
- [TUTORIAL_ADD_BLOCK.md](./TUTORIAL_ADD_BLOCK.md) — добавить новый тип блока
|
||
- [TUTORIAL_DEBUG_BABYLON.md](./TUTORIAL_DEBUG_BABYLON.md) — отладка 3D-сцены
|
||
- [API_USAGE.md](../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 и поехали.
|