# Contributing to WarpBox

WarpBox is a small Go application with server-rendered HTML, vanilla
JavaScript, static CSS, local filesystem storage, and BadgerDB metadata. Keep
changes boring, readable, and easy to review.

## Setup

Requirements:

- Go 1.23 or newer, matching `go.mod`.
- No frontend toolchain. Do not add npm, Vite, React, TypeScript, Sass,
  Tailwind, or a JavaScript build step for cleanup work.

Run the app:

```bash
go run ./cmd run
```

Run on another address:

```bash
go run ./cmd run --addr :3000
```

## Tests and Checks

Run tests:

```bash
./test.sh
```

Run formatting, vet, and tests:

```bash
./check.sh
```

Both scripts honor `GO_BIN`:

```bash
GO_BIN=/path/to/go ./check.sh
```

If a command cannot run in your environment, say why and include the command
that should be run locally.

## Commit Style

Use Conventional Commits:

```text
type(scope): short imperative subject
```

Types:

- `feat` user-visible feature
- `fix` bug fix
- `refactor` behavior-preserving code change
- `test` tests only
- `docs` documentation only
- `style` formatting or CSS-only visual style when behavior unchanged
- `chore` tooling, dependency, build, housekeeping
- `perf` performance change
- `ci` CI config

Rules:

- Keep subject at 72 characters or less, preferably 50 or less.
- Use imperative mood.
- Keep one concern per commit.
- Make cleanup commits behavior preserving unless the subject says `fix`.
- Mention tests run in the PR description or commit body when useful.

Examples:

```text
docs(contributing): add cleanup rules
refactor(server): split upload handlers
fix(config): reject negative expiry values
```

## Code Review Expectations

Reviews should focus on behavior, safety, and maintainability:

- Confirm routes, environment variables, API response shapes, manifest fields,
  and storage layout remain compatible unless the change explicitly updates
  them.
- Check that cleanup keeps behavior unchanged and is small enough to review.
- Prefer narrow helpers and clear file ownership over clever abstraction.
- Ask for tests when behavior changes or risk is not obvious.
- Call out missing checks, unclear edge cases, concurrency risks, and security
  risks.

## PR Checklist

Before opening or merging a PR:

- Scope is limited to one concern.
- Runtime behavior is unchanged for cleanup PRs.
- Public routes are unchanged unless intentional.
- Environment variables are unchanged unless intentional.
- API response shapes are unchanged unless intentional.
- Manifest JSON field names are unchanged unless intentional.
- Storage directory layout is unchanged unless intentional.
- No frontend build tooling was added.
- Tests or checks run are listed.

## Coding Standards Summary

- Go: small functions, clear errors, stable exported names, no unrelated
  package moves.
- JavaScript: vanilla browser scripts, no build step, explicit state ownership,
  small modules when files are split.
- CSS: keep shared styles shared, page styles page-scoped, avoid duplicated
  popup/window rules.
- Templates: keep server-rendered HTML simple and routes stable.
- Comments: explain behavior rules, edge cases, concurrency, security, or
  product choices. Do not restate obvious code.

See [DEVELOPMENT.md](DEVELOPMENT.md) for cleanup rules.