130 lines
5.2 KiB
Markdown
130 lines
5.2 KiB
Markdown
# Contributing to Cozy Games
|
|
|
|
Thanks for your interest in contributing! This guide covers what you need to
|
|
develop, test, and submit changes.
|
|
|
|
> Working as an AI coding agent? See [AGENTS.md](AGENTS.md) for machine-oriented
|
|
> guidance. This document is for human contributors.
|
|
|
|
## Prerequisites
|
|
|
|
- **Node.js** — the version pinned in [`.nvmrc`](.nvmrc) (`lts/*`). With
|
|
[nvm](https://github.com/nvm-sh/nvm): `nvm use`.
|
|
- **pnpm** — **pnpm is required** (npm/yarn will not work). The repo pins its
|
|
pnpm version via the
|
|
`packageManager` field, so the simplest way to get the right one is Corepack:
|
|
`corepack enable`.
|
|
- **Java (JDK 11+, 21 recommended)** — only needed to run the local Firestore
|
|
emulator (used by the mnswpr app's leaderboard in development). `pnpm install`
|
|
tries to install a user-local Temurin JRE automatically; if that is skipped (CI
|
|
or an unsupported platform) install a JDK yourself. You can avoid Java entirely
|
|
with the `dev:no-db` script below.
|
|
|
|
## Project Structure
|
|
|
|
This repo is a single package at the root — the mnswpr.com web app. `main.js`
|
|
and `index.html` are the app itself, `modules/` holds the app-owned services,
|
|
`scripts/` holds tooling, and `docs/` documents the backend. The game engine and
|
|
leaderboard come from npm ([ayo-run/cozy-games](https://github.com/ayo-run/cozy-games));
|
|
there is no local `packages/` to edit.
|
|
|
|
Backend config (Firestore rules, Firebase project aliases, Netlify hosting) is
|
|
committed at the root — see [AGENTS.md](AGENTS.md) "Infra".
|
|
|
|
## Setup
|
|
|
|
```bash
|
|
pnpm i # install dependencies
|
|
```
|
|
|
|
## Commands (all run from the repo root)
|
|
|
|
```bash
|
|
pnpm test # run the whole test suite once (Vitest, jsdom)
|
|
pnpm test:watch # tests in watch mode
|
|
pnpm lint # eslint (JS + CSS)
|
|
pnpm lint:fix # eslint --fix
|
|
```
|
|
|
|
## Running the game locally
|
|
|
|
```bash
|
|
pnpm run dev # Vite dev server + Firestore emulator (auto-seeded) — needs Java
|
|
pnpm run dev:no-db # Vite only, no emulator (UI work, or no Java)
|
|
pnpm run build # build the app -> dist
|
|
pnpm run preview # preview the production build
|
|
```
|
|
|
|
## Tests
|
|
|
|
Tests run under **Vitest** with a **jsdom** environment and live next to the code
|
|
they exercise (`test/`, `scripts/test/`). They drive real behavior — e.g. mounting the
|
|
game and dispatching DOM events — not just isolated unit calls. Run `pnpm test`
|
|
(or `pnpm test:watch`) before opening a PR, and add tests for new behavior.
|
|
|
|
## Code style
|
|
|
|
Style is enforced by **ESLint (Stylistic)**, not Prettier:
|
|
|
|
- 2-space indent, single quotes, **no semicolons**, no trailing commas
|
|
- spaces inside `{ braces }` but not `[brackets]`
|
|
- both `**/*.js` and `**/*.css` are linted
|
|
|
|
Run `pnpm lint:fix` before committing. The codebase is **plain JavaScript with
|
|
JSDoc + `// @ts-check`** — no TypeScript. Match the style and patterns of the file
|
|
you're editing (`modules/` uses ES classes; `scripts/` uses plain functions).
|
|
|
|
A **pre-commit hook** runs the linter and a secret scan automatically — commits
|
|
fail if either does. Keep credentials and any `.env.production` out of commits.
|
|
|
|
## Infra & local backend (optional)
|
|
|
|
Only relevant if you're working on backend-touching features. Every app **owns its
|
|
own backend config** (declarative, committed in-repo) and its tooling (CLIs as
|
|
devDependencies) — no web dashboards. For mnswpr (Firestore + Netlify), the local
|
|
DB emulator is all a contributor needs:
|
|
|
|
```bash
|
|
pnpm run db:start # start the local Firestore emulator (standalone) — needs Java
|
|
pnpm run db:seed # seed the running emulator with sample data
|
|
pnpm run db:stop # stop a stray emulator holding :8080
|
|
```
|
|
|
|
Deploy scripts (`deploy:db`, `deploy:site`) also exist but require project
|
|
credentials, so they're for maintainers. See [README.md](README.md) and
|
|
[`docs/`](docs/) for the full backend reference.
|
|
|
|
## Project structure
|
|
|
|
The repo layout and architecture are documented in [AGENTS.md](AGENTS.md) —
|
|
worth a read before a large change.
|
|
|
|
## Submitting changes
|
|
|
|
1. Create a branch off `main`.
|
|
2. Make a focused change.
|
|
3. Run `pnpm lint` and `pnpm test` — both must pass.
|
|
4. Write clear, conventional commit messages (`feat:`, `fix:`, `chore:`, …).
|
|
5. Open a pull request describing **what** changed and **why**; link any related issue.
|
|
|
|
For anything large, open an issue to discuss the approach first.
|
|
|
|
## Commit & PR hygiene
|
|
|
|
Write commit messages in plain project voice — what changed and why. Keep them
|
|
free of AI-tool attribution trailers or footers (including `Co-Authored-By:`
|
|
lines crediting a coding assistant) and of session links; the same goes for PR
|
|
titles and bodies. Co-authoring with another *person* is always fine — use any
|
|
address you like, there is no contributor allowlist.
|
|
|
|
CI also checks your changes against a maintainer-managed reserved-terms list. If a
|
|
check flags your change, reword it — or ask a maintainer if it isn't clear why.
|
|
The checks run locally too: the pre-commit hook scans staged changes and your
|
|
branch name, and the commit-msg hook scans the message. If a line legitimately
|
|
needs wording a check objects to (prose *about* these topics, say), put a
|
|
`content-policy: allow-next-line` comment above it and mention why in the PR.
|
|
|
|
## License
|
|
|
|
By contributing, you agree that your contributions are licensed under the
|
|
project's [MIT license](LICENSE).
|