# Contributing to Sky Phone

Sky Phone uses `dev` as its default integration branch. All normal changes reach `dev` through a pull request; do not push feature work directly to it.

## Branches

Create a short-lived branch from an up-to-date `dev` branch. Use lowercase kebab-case after one of these prefixes:

| Prefix      | Purpose                                          |
| ----------- | ------------------------------------------------ |
| `feat/`     | New behavior or app capability                   |
| `fix/`      | Bug fix                                          |
| `hotfix/`   | Urgent release repair                            |
| `docs/`     | Documentation only                               |
| `refactor/` | Internal change without intended behavior change |
| `perf/`     | Performance work                                 |
| `test/`     | Test-only work                                   |
| `build/`    | Build or packaging work                          |
| `ci/`       | GitHub Actions and repository automation         |
| `chore/`    | Focused maintenance                              |
| `release/`  | Release preparation                              |

`feature/` remains accepted for existing branches, but new feature branches should use `feat/`.

Examples: `feat/mail-signatures`, `fix/radio-focus`, `ci/release-package`. Avoid personal names, issue titles, uppercase characters, spaces, and branches that combine unrelated work.

## Commits and pull requests

Use the repository commit format:

```text
TAG - short imperative summary
```

Allowed tags are `ENH`, `ADD`, `FIX`, `DOC`, `BLD`, `PERF`, `CLN`, and `TRY`. Examples:

```text
FIX - validate mail ownership before deletion
ENH - add per-account notification settings
DOC - clarify Qbox installation order
```

Use the same format for the pull request title. Keep commits focused, stage only task files, link the issue, and complete the pull request template with actual commands and results.

## Architecture and security rules

- Sky Phone is standalone. It must not depend on or exchange state with `sky_base`, `sky_jobs_base`, or another `sky_*` resource.
- The server validates and decides permissions, identity, money, inventory, ownership, proximity, limits, and all other consequential state.
- Treat NUI and client payloads as untrusted. Every NUI callback must invoke its response callback on every reachable path.
- Parameterize SQL, keep persistence owned by `sky_phone`, and send only the required data over the network.
- Keep credentials, tokens, private endpoints, and player-identifying data out of source, fixtures, logs, issues, and pull requests.

## Schema, configuration, and compatibility

- Prefix new resource-owned tables, persistent keys, convars, callbacks, and events with `sky_phone` where the technology permits it.
- Keep the runtime schema in `sky_phone/source/server/db_migrate.lua` and the clean-install schema in `sky_phone/sql/install.sql` aligned.
- Prefer additive, idempotent migrations. Destructive or lossy migrations require an explicit migration plan, backup guidance, and reviewer approval.
- Do not force a database charset or collation unless a documented compatibility requirement has been reviewed.
- Preserve public events, callbacks, exports, configuration defaults, and stored data unless the linked issue explicitly authorizes a breaking change.
- Update both English and German locales for user-facing text. Logs and developer diagnostics remain in English.
- New or substantially changed NUI screens use the public Sky UI components and semantic tokens under `frontend/src/ui`.

## Local validation

Install frontend dependencies with pnpm, then run the checks relevant to the change:

```powershell
cd frontend
pnpm install --frozen-lockfile
pnpm typecheck
pnpm lint
pnpm test
pnpm build
```

The build publishes the generated NUI into `sky_phone/source/html`. Do not hand-edit generated output. A successful build proves source/build consistency, not behavior inside FiveM; report live runtime testing separately.

Every pull request also receives an automated CodeQL scan and dependency review. After the full CI run succeeds, GitHub packages the deployable `sky_phone` folder as a test-resource ZIP and adds or updates a download link in the pull request. The artifact is retained for 14 days. It is suitable for manual testing on a test server, but it is not a release and does not replace live FiveM validation.

Lua, config, manifest, locale, SQL, and native changes must also be tested in a restarted FiveM resource with experimental OAL enabled. Pass native coordinates as separate numeric arguments and verify native signatures against authoritative documentation.

## Review and merge

A pull request is ready when the repository policy, frontend, CodeQL, dependency review, and pull-request policy checks pass; review conversations are resolved; the latest push is approved by someone other than its author; and migrations or operational steps are explicit. Automated findings complement rather than replace the human maintainer review. Anyone may open a pull request, but only collaborators with the built-in GitHub `Maintain` role may merge into `dev`. Maintainers must merge through a pull request; the ruleset does not permit direct pushes to `dev`. The default ruleset allows merge, squash, and rebase so maintainers can preserve meaningful merge history when needed.

Release tags use numeric semantic versions without a `v` prefix, for example `0.2.0`. Tags are immutable after creation.