# Contributing to Runic Gateway — Website

Thanks for your interest in contributing! This repo is the full-stack website
(Node.js + Express API, MariaDB, React + Vite SPA). This guide covers how to get
set up, the workflow we follow, and the rules for contributions.

By participating you agree to abide by our
[Code of Conduct](CODE_OF_CONDUCT.md).

## Ways to contribute

- **Report a bug** or **request a feature** through the
  [issue tracker](https://gitea.whitlocktech.com/RunicGateway/website/issues)
  (issue templates are provided).
- **Improve the code or docs** by opening a pull request (see below).
- **Never** report a security vulnerability in a public issue — see
  [SECURITY.md](SECURITY.md).

## Development setup

**Prerequisites:** Node.js 20+ and npm, plus Docker (for MariaDB).

The [README](README.md) has the full setup guide. The short version for local
development with hot reload:

```bash
# 1. Start a MariaDB the backend can reach
docker run -d --name rg-db -p 3306:3306 \
  -e MARIADB_DATABASE=runic_gateway -e MARIADB_USER=runic \
  -e MARIADB_PASSWORD=devpass -e MARIADB_ROOT_PASSWORD=rootpass mariadb:11

# 2. Backend (terminal 1)
cp server/.env.example server/.env   # set DB_* , JWT_SECRET, ADMIN_USERNAME/PASSWORD
npm run install-all
npm run server                       # nodemon -> http://localhost:3000

# 3. Frontend (terminal 2)
npm run client                       # Vite -> http://localhost:5173
```

Develop against **http://localhost:5173** (the Vite dev server proxies `/api`).

### Tests & checks

Please run the server test suite and make sure the client builds before opening
a PR — these are the same checks CI runs on your PR:

```bash
npm test            # server tests
npm run build       # client production build
```

If you add or change an API route, regenerate the Swagger spec
(`cd server && npm run swagger`) and commit the updated
`server/swagger/swagger-output.json`.

## Branch & PR workflow

1. Fork or branch from `main`. Use a descriptive branch name
   (`feature/…`, `fix/…`, `docs/…`, `chore/…`).
2. Keep changes focused; small PRs are easier to review.
3. Push and open a pull request against `main`. Fill out the PR template,
   including the **AI-assisted contributions** disclosure.
4. Make sure PR checks (server tests + client build) are green.
5. A maintainer will review; address feedback by pushing follow-up commits.

### Commit messages

We use [Conventional Commits](https://www.conventionalcommits.org/) —
`type(scope): summary` (e.g. `feat(auth): add TOTP challenge step`,
`fix(brand): link footer badge to Gitea org`). Common types: `feat`, `fix`,
`docs`, `chore`, `refactor`, `test`, `ci`.

## AI-assisted contributions (disclosure required)

This project is developed openly with AI assistance, and we ask the same
transparency of everyone. **If you used an AI tool** (Claude, Copilot, ChatGPT,
Cursor, etc.) to help produce a contribution, you must disclose it:

- Tick the AI-usage box in the pull-request template and name the tool(s).
- Mark AI-authored commits with a trailer, e.g.
  `Co-Authored-By: Claude <noreply@anthropic.com>` or `Assisted-By: <tool>`.
- You remain responsible for every line you submit: review it, understand it,
  and make sure it is correct and that you have the right to contribute it.

Disclosed AI assistance is welcome. Undisclosed AI-generated contributions are
not, and may be closed.

## License

Runic Gateway is licensed under the **GNU General Public License v3.0 or later**
(see [LICENSE.md](LICENSE.md)). By submitting a contribution you agree that it is
licensed under the same terms (inbound = outbound) and that you have the right to
contribute it.