# Contributing to Rublox Player

Thanks for your interest! Here's everything you need to know.

## Before your first PR

1. **Sign the [CLA](./CLA.md)** — open `https://team.rublox.pro/developer/cla` (you need a `developer` role; ask the maintainer) OR comment `/sign-cla` on your PR.
2. **Have a Gitea account** linked via OAuth to team.rublox.pro.
3. **Add your SSH key** to Gitea profile (otherwise you push by HTTPS + password).

## Workflow

```bash
# 1. Fork or clone (you can push to a feature branch directly if you have access)
git clone ssh://git@git.rublox.pro:2222/rublox/player.git
cd player
npm install
cp .env.example .env

# 2. Create a feature branch
git checkout -b feature/short-description

# 3. Make changes
npm run dev      # test locally
npm run lint     # check ESLint
npm run format   # apply Prettier

# 4. Commit (Conventional Commits)
git commit -m "feat: add jump animation to GdBall"
# Other prefixes: fix:, chore:, docs:, refactor:, test:, perf:, ci:

# 5. Push and open PR
git push origin feature/short-description
# Open PR via https://git.rublox.pro/rublox/player
```

## Code style

We use **Prettier** (auto-format) + **ESLint** (lint). The config is committed in `.prettierrc` and `.eslintrc.json`.

Key rules:
- 2-space indent
- Single quotes (`'foo'`, not `"foo"`)
- Semicolons required
- Trailing comma in multi-line literals
- 100-char line width
- No `eval`, no `new Function`, no `innerHTML = ...`
- React: hooks rules enforced (`react-hooks/rules-of-hooks`)

Run before commit:
```bash
npm run format    # auto-fixes most things
npm run lint      # warns about the rest
```

A pre-commit hook (Husky, if installed) will block you if Prettier check fails.

## Branch naming

| Prefix | Use for |
|---|---|
| `feature/...` | New features |
| `fix/...` | Bug fixes |
| `chore/...` | Refactoring, deps, tooling |
| `docs/...` | Documentation only |
| `perf/...` | Performance improvements |

## Commit messages (Conventional Commits)

```
<type>: <short description>

[optional body]

[optional footer: BREAKING CHANGE / Closes #N]
```

Types: `feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `perf`, `ci`, `style`.

**Good:**
- `feat: add WaveMode to GdGameModeRegistry`
- `fix: ScriptSandbox crashes on Worker timeout`
- `perf: throttle ui.set() to 250ms with diff check`

**Bad:**
- `update code`
- `wip`
- `fixed stuff`

## PR template

When you open a PR, fill in:

```markdown
## What

(1-2 sentences: what does this PR do?)

## Why

(motivation: bug report, feature request, related issue #N)

## How to test

(reproducible steps a reviewer can run)

## Screenshots / video (if UI change)

## Checklist

- [ ] `npm run lint` passes
- [ ] `npm run format:check` passes
- [ ] `npm run build` succeeds
- [ ] Tested locally with `npm run dev`
- [ ] Updated relevant docs (README / ARCHITECTURE / CHANGELOG)
- [ ] CLA signed
```

## Review process

- The repo maintainer (МИН) reviews every PR.
- Expect feedback within **48 hours** (often same day).
- Small PRs (<300 lines changed) get reviewed fast. PRs >1000 lines will be asked to split.
- After approval, **maintainer merges** (only the maintainer has merge permission).
- After merge, an automated webhook triggers production deploy.

## What we won't merge

- PRs that add new external dependencies without discussion
- PRs that touch sensitive paths (`engine/scripts/ScriptSandbox*.js`, `engine/multiplayer/*`) without security review
- PRs that break the build or lint
- PRs from contributors who haven't signed the CLA
- Massive refactors without a tracking issue discussed beforehand

## What we love

- Bug fixes with reproducible test cases
- Performance improvements with before/after metrics
- New `engine/gd/Gd*.js` gamemodes
- New script API additions (in `ScriptSandboxAPI.js`)
- Documentation improvements (especially examples)

## Security

Found a vulnerability? **Don't open a public issue.** Email `security@rublox.pro` directly. See [SECURITY.md](./SECURITY.md).

## Questions?

- Open an issue with the **Question** label
- Or hop into the `#разработка` channel at https://team.rublox.pro/chat